httpsms

package module
v0.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 5, 2026 License: MIT Imports: 16 Imported by: 1

README

httpsms-go

Build codecov Scrutinizer Code Quality Go Report Card GitHub contributors GitHub license PkgGoDev

This package provides a generic go client template for the Http SMS Api

Installation

httpsms-go is compatible with modern Go releases in module mode, with Go installed:

go get github.com/NdoleStudio/httpsms-go

Alternatively the same can be achieved if you use import in a package:

import "github.com/NdoleStudio/httpsms-go"

Implemented

  • Messages
    • POST /v1/messages/send: Send a new SMS
    • GET /v1/messages: Get list of messages which are exchanged between 2 phone numbers.
  • Heartbeats
    • GET /v1/heartbeats: Get the heartbeats of an Android Phone
  • Message Threads
    • GET /v1/message-threads: Get the message threads of a phone number
    • DELETE v1/message-threads/:messageThreadID: Delete a message thread
  • Cipher
    • Encrypt: Encrypt the content of a message to cipher text
    • Decrypt: Decrypt an encrypted message content to plain text

Usage

Initializing the Client

An instance of the client can be created using httpsms.New().

package main

import (
    "github.com/NdoleStudio/httpsms-go"
)

func main()  {
    client := htpsms.New(htpsms.WithAPIKey(/* API Key from https://httpsms.com/settings */))
}
Error handling

All API calls return an error as the last return object. All successful calls will return a nil error.

_, response, err := client.Messages.Send(context.Background())
if err != nil {
    //handle error
}
Messages
POST /v1/messages/send: Send a new SMS Message
message, response, err := client.Messages.Send(context.Background(), &MessageSendParams{
    Content: "This is a sample text message",
    From:    "+18005550199",
    To:      "+18005550100",
})

if err != nil {
    log.Fatal(err)
}

log.Println(message.Code) // 202

Testing

You can run the unit tests for this client from the root directory using the command below:

go test -v

License

This project is licensed under the MIT License - see the LICENSE file for details

Documentation

Index

Constants

View Source 
const EventTypeMessageCallMissed = "message.call.missed"

EventTypeMessageCallMissed is emitted when a new message is sent

View Source 
const EventTypeMessagePhoneDelivered = "message.phone.delivered"

EventTypeMessagePhoneDelivered is emitted when the phone delivers a message

View Source 
const EventTypeMessagePhoneReceived = "message.phone.received"

EventTypeMessagePhoneReceived is emitted when a new message is received by a mobile phone

View Source 
const EventTypeMessagePhoneSent = "message.phone.sent"

EventTypeMessagePhoneSent is emitted when the phone sends a message

View Source 
const EventTypeMessageSendExpired = "message.send.expired"

EventTypeMessageSendExpired is emitted when the phone a message expires

View Source 
const EventTypeMessageSendFailed = "message.send.failed"

EventTypeMessageSendFailed is emitted when the phone could not send

View Source 
const EventTypePhoneHeartbeatOffline = "phone.heartbeat.offline"

EventTypePhoneHeartbeatOffline is emitted when the phone is missing a heartbeat

View Source 
const EventTypePhoneHeartbeatOnline = "phone.heartbeat.online"

EventTypePhoneHeartbeatOnline is emitted when the phone is missing a heartbeat

Variables

This section is empty.

Functions

This section is empty.

Types

type ApiResponse added in v0.0.2 

type ApiResponse[T any] struct {
	Data    T      `json:"data"`
	Message string `json:"message"`
	Status  string `json:"status"`
}

type CipherService added in v0.0.5 

type CipherService service

CipherService is used to encrypt and decrypt SMS messages using the AES-256 algorithm

func (*CipherService) Decrypt added in v0.0.5 

func (service *CipherService) Decrypt(encryptionKey string, cipherText string) (string, error)

Decrypt the message content using the encryption key

func (*CipherService) Encrypt added in v0.0.5 

func (service *CipherService) Encrypt(encryptionKey string, content string) (string, error)

Encrypt the message content using the encryption key

type Client 

type Client struct {
	MessageThreads *MessageThreadService
	Heartbeats     *HeartbeatService
	Messages       *MessageService
	Cipher         *CipherService
	Phones         *PhoneService
	PhoneAPIKeys   *PhoneAPIKeyService
	Webhooks       *WebhookService
	// contains filtered or unexported fields
}

Client is the campay API client. Do not instantiate this client with Client{}. Use the New method instead.

func New 

func New(options ...Option) *Client

New creates and returns a new campay.Client from a slice of campay.ClientOption.

type Heartbeat added in v0.0.2 

type Heartbeat struct {
	ID        uuid.UUID `json:"id" example:"32343a19-da5e-4b1b-a767-3298a73703cb"`
	Owner     string    `json:"owner" gorm:"index:idx_heartbeats_owner_timestamp" example:"+18005550199"`
	UserID    string    `json:"user_id" example:"WB7DRDWrJZRGbYrv2CKGkqbzvqdC"`
	Charging  bool      `json:"charging" example:"true"`
	Timestamp time.Time `json:"timestamp" example:"2022-06-05T14:26:01.520828+03:00"`
}

Heartbeat represents is a pulse from an active phone

type HeartbeatIndexParams added in v0.0.2 

type HeartbeatIndexParams struct {
	Skip  int     `json:"skip"`
	Owner string  `json:"owner"`
	Query *string `json:"query"`
	Limit int     `json:"limit"`
}

HeartbeatIndexParams is the payload for fetching entities.Heartbeat of a phone number

type HeartbeatService added in v0.0.2 

type HeartbeatService service

HeartbeatService is the API client for the `/heartbeats` endpoint

func (*HeartbeatService) Index added in v0.0.2 

func (service *HeartbeatService) Index(ctx context.Context, params *HeartbeatIndexParams) (*HeartbeatsResponse, *Response, error)

Index returns a list of heartbeats from an android phone. It will be sorted by timestamp in descending order.

API Docs: https://api.httpsms.com/index.html#/Heartbeats/get_heartbeats

type HeartbeatsResponse added in v0.0.2 

type HeartbeatsResponse ApiResponse[[]Heartbeat]

HeartbeatsResponse is the response gotten with a message content

type Message 

type Message struct {
	ID        uuid.UUID `json:"id" example:"32343a19-da5e-4b1b-a767-3298a73703cb"`
	RequestID *string   `json:"request_id" example:"153554b5-ae44-44a0-8f4f-7bbac5657ad4"`
	Owner     string    `json:"owner" example:"+18005550199"`
	UserID    string    `json:"user_id" example:"WB7DRDWrJZRGbYrv2CKGkqbzvqdC"`
	Contact   string    `json:"contact" example:"+18005550100"`
	Content   string    `json:"content" example:"This is a sample text message"`
	Type      string    `json:"type" example:"mobile-terminated"`
	Status    string    `json:"status" example:"pending"`
	Encrypted bool      `json:"encrypted" example:"false"`

	// SIM is the SIM card to use to send the message
	// * SMS1: use the SIM card in slot 1
	// * SMS2: use the SIM card in slot 2
	SIM string `json:"sim" example:"SIM1"`

	// SendDuration is the number of nanoseconds from when the request was received until when the mobile phone send the message
	SendDuration *int64 `json:"send_time" example:"133414"`

	RequestReceivedAt       time.Time  `json:"request_received_at" example:"2022-06-05T14:26:01.520828+03:00"`
	CreatedAt               time.Time  `json:"created_at" example:"2022-06-05T14:26:02.302718+03:00"`
	UpdatedAt               time.Time  `json:"updated_at" example:"2022-06-05T14:26:10.303278+03:00"`
	OrderTimestamp          time.Time  `json:"order_timestamp" gorm:"index:idx_messages_order_timestamp" example:"2022-06-05T14:26:09.527976+03:00"`
	LastAttemptedAt         *time.Time `json:"last_attempted_at" example:"2022-06-05T14:26:09.527976+03:00"`
	NotificationScheduledAt *time.Time `json:"scheduled_at" example:"2022-06-05T14:26:09.527976+03:00"`
	SentAt                  *time.Time `json:"sent_at" example:"2022-06-05T14:26:09.527976+03:00"`
	DeliveredAt             *time.Time `json:"delivered_at" example:"2022-06-05T14:26:09.527976+03:00"`
	ExpiredAt               *time.Time `json:"expired_at" example:"2022-06-05T14:26:09.527976+03:00"`
	FailedAt                *time.Time `json:"failed_at" example:"2022-06-05T14:26:09.527976+03:00"`
	CanBePolled             bool       `json:"can_be_polled" example:"false"`
	SendAttemptCount        uint       `json:"send_attempt_count" example:"0"`
	MaxSendAttempts         uint       `json:"max_send_attempts" example:"1"`
	ReceivedAt              *time.Time `json:"received_at" example:"2022-06-05T14:26:09.527976+03:00"`
	FailureReason           *string    `json:"failure_reason" example:"UNKNOWN"`
}

Message represents and incoming or outgoing SMS message

type MessageIndexParams added in v0.0.2 

type MessageIndexParams struct {
	Skip    int     `json:"skip"`
	Contact string  `json:"contact"`
	Owner   string  `json:"owner"`
	Query   *string `json:"query"`
	Limit   int     `json:"limit"`
}

MessageIndexParams is the payload fetching entities.Message sent between 2 numbers

type MessageResponse 

type MessageResponse ApiResponse[Message]

MessageResponse is the response gotten with a message content

type MessageSendParams 

type MessageSendParams struct {
	Content   string `json:"content"`
	From      string `json:"from"`
	Encrypted bool   `json:"encrypted"`
	RequestID string `json:"request_id,omitempty"`
	To        string `json:"to"`
}

MessageSendParams is the request payload for sending a message

type MessageService added in v0.0.2 

type MessageService service

MessageService is the API client for the `/` endpoint

func (*MessageService) Index added in v0.0.2 

func (service *MessageService) Index(ctx context.Context, params *MessageIndexParams) (*MessagesResponse, *Response, error)

Index returns a list of messages which are sent between 2 phone numbers. It will be sorted by timestamp in descending order.

API Docs: https://api.httpsms.com/index.html#/Messages/get_messages

func (*MessageService) Send added in v0.0.2 

func (service *MessageService) Send(ctx context.Context, params *MessageSendParams) (*MessageResponse, *Response, error)

Send adds a new SMS message to be sent by the android phone

API Docs: https://api.httpsms.com/index.html#/Messages/post_messages_send

type MessageThread added in v0.0.2 

type MessageThread struct {
	ID                 uuid.UUID `json:"id" example:"32343a19-da5e-4b1b-a767-3298a73703ca"`
	Owner              string    `json:"owner" example:"+18005550199"`
	Contact            string    `json:"contact" example:"+18005550100"`
	IsArchived         bool      `json:"is_archived" example:"false"`
	UserID             string    `json:"user_id" example:"WB7DRDWrJZRGbYrv2CKGkqbzvqdC"`
	Color              string    `json:"color" example:"indigo"`
	Status             string    `json:"status" example:"pending"`
	LastMessageContent string    `json:"last_message_content" example:"This is a sample message content"`
	LastMessageID      uuid.UUID `json:"last_message_id" example:"32343a19-da5e-4b1b-a767-3298a73703ca"`
	CreatedAt          time.Time `json:"created_at" example:"2022-06-05T14:26:09.527976+03:00"`
	UpdatedAt          time.Time `json:"updated_at" example:"2022-06-05T14:26:09.527976+03:00"`
	OrderTimestamp     time.Time `json:"order_timestamp"  example:"2022-06-05T14:26:09.527976+03:00"`
}

MessageThread represents a message thread between 2 phone numbers

type MessageThreadIndexParams added in v0.0.2 

type MessageThreadIndexParams struct {
	IsArchived bool    `json:"is_archived"`
	Skip       int     `json:"skip"`
	Query      *string `json:"query"`
	Limit      int     `json:"limit"`
	Owner      string  `json:"owner"`
}

MessageThreadIndexParams is the payload fetching entities.MessageThread sent between 2 numbers

type MessageThreadService added in v0.0.2 

type MessageThreadService service

MessageThreadService is the API client for the `/message-threads` endpoint

func (*MessageThreadService) Delete added in v0.0.6 

func (service *MessageThreadService) Delete(ctx context.Context, messageThreadID uuid.UUID) (*Response, error)

Delete a message thread from the database and also deletes all the messages in the thread.

API Docs: https://api.httpsms.com/index.html#/MessageThreads/delete_message_threads__messageThreadID_

func (*MessageThreadService) Index added in v0.0.2 

func (service *MessageThreadService) Index(ctx context.Context, params *MessageThreadIndexParams) (*MessageThreadsResponse, *Response, error)

Index returns a list of contacts which a phone number has communicated with (threads). It will be sorted by timestamp in descending order.

API Docs: https://api.httpsms.com/index.html#/Channel%20Threads/get_message_threads

type MessageThreadsResponse added in v0.0.2 

type MessageThreadsResponse ApiResponse[[]MessageThread]

MessageThreadsResponse is the response gotten with a message content

type MessagesResponse added in v0.0.2 

type MessagesResponse ApiResponse[[]Message]

MessagesResponse is the response with multiple messages

type Option 

type Option interface {
	// contains filtered or unexported methods
}

Option is options for constructing a client

func WithAPIKey 

func WithAPIKey(apiKey string) Option

WithAPIKey sets the api key for the httpsms API

func WithBaseURL 

func WithBaseurl(/Education?url=https%3A%2F%2Fpkg.go.dev%2Fgithub.com%2FNdoleStudio%2FbaseURL%2520%253Ca%2520href%3D%2522%2FEducation%3Furl%3Dhttps%253A%252F%252Fpkg.go.dev%252Fbuiltin%2523string%2522%253Estring%253C%2Fa%253E) Option

WithBaseURL sets the base url for the httpsms API

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient sets the underlying HTTP client used for API requests. By default, http.DefaultClient is used.

type Phone added in v0.0.8 

type Phone struct {
	ID                       string    `json:"id"`
	UserID                   string    `json:"user_id"`
	PhoneNumber              string    `json:"phone_number"`
	FcmToken                 *string   `json:"fcm_token"`
	MessagesPerMinute        uint      `json:"messages_per_minute"`
	MaxSendAttempts          uint      `json:"max_send_attempts"`
	MessageExpirationSeconds uint      `json:"message_expiration_seconds"`
	SIM                      string    `json:"sim"`
	CreatedAt                time.Time `json:"created_at"`
	UpdatedAt                time.Time `json:"updated_at"`
}

Phone represents a phone registered in the httpSMS API

type PhoneAPIKey added in v0.0.8 

type PhoneAPIKey struct {
	ID           string    `json:"id"`
	Name         string    `json:"name"`
	UserID       string    `json:"user_id"`
	UserEmail    string    `json:"user_email"`
	PhoneNumbers []string  `json:"phone_numbers"`
	PhoneIDs     []string  `json:"phone_ids"`
	APIKey       string    `json:"api_key"`
	CreatedAt    time.Time `json:"created_at"`
	UpdatedAt    time.Time `json:"updated_at"`
}

PhoneAPIKey represents a phone API key

type PhoneAPIKeyResponse added in v0.0.8 

type PhoneAPIKeyResponse ApiResponse[PhoneAPIKey]

PhoneAPIKeyResponse is the response gotten with a phone api key

type PhoneAPIKeyService added in v0.0.8 

type PhoneAPIKeyService service

PhoneAPIKeyService is the API client for the phone api key endpoints

func (*PhoneAPIKeyService) Store added in v0.0.8 

func (service *PhoneAPIKeyService) Store(ctx context.Context, params *PhoneAPIKeyStoreParams) (*PhoneAPIKeyResponse, *Response, error)

Store adds a new phone api key

type PhoneAPIKeyStoreParams added in v0.0.8 

type PhoneAPIKeyStoreParams struct {
	Name string `json:"name"`
}

PhoneAPIKeyStoreParams is the request payload for creating a phone api key

type PhoneFCMTokenParams added in v0.0.8 

type PhoneFCMTokenParams struct {
	PhoneNumber string `json:"phone_number"`
	FcmToken    string `json:"fcm_token"`
	SIM         string `json:"sim,omitempty"`
}

PhoneFCMTokenParams is the request for binding FCM token to a phone via phone API key

type PhoneResponse added in v0.0.8 

type PhoneResponse ApiResponse[Phone]

PhoneResponse is the response gotten with a phone

type PhoneService added in v0.0.8 

type PhoneService service

PhoneService is the API client for the phone endpoints

func (*PhoneService) Upsert added in v0.0.8 

func (service *PhoneService) Upsert(ctx context.Context, params *PhoneUpsertParams) (*PhoneResponse, *Response, error)

Upsert creates or updates a phone

func (*PhoneService) UpsertFCMToken added in v0.0.8 

func (service *PhoneService) UpsertFCMToken(ctx context.Context, params *PhoneFCMTokenParams) (*PhoneResponse, *Response, error)

UpsertFCMToken binds an FCM token to a phone via the phone API key

type PhoneUpsertParams added in v0.0.8 

type PhoneUpsertParams struct {
	PhoneNumber              string `json:"phone_number"`
	FcmToken                 string `json:"fcm_token,omitempty"`
	MessagesPerMinute        uint   `json:"messages_per_minute,omitempty"`
	MaxSendAttempts          uint   `json:"max_send_attempts,omitempty"`
	MessageExpirationSeconds uint   `json:"message_expiration_seconds,omitempty"`
	SIM                      string `json:"sim,omitempty"`
}

PhoneUpsertParams is the request payload for creating/updating a phone

type Response 

type Response struct {
	HTTPResponse *http.Response
	Body         *[]byte
}

Response captures the http response

func (*Response) Error 

func (r *Response) Error() error

Error ensures that the response can be decoded into a string inc ase it's an error response

type Webhook added in v0.0.8 

type Webhook struct {
	ID           string    `json:"id"`
	UserID       string    `json:"user_id"`
	URL          string    `json:"url"`
	SigningKey   string    `json:"signing_key"`
	PhoneNumbers []string  `json:"phone_numbers"`
	Events       []string  `json:"events"`
	CreatedAt    time.Time `json:"created_at"`
	UpdatedAt    time.Time `json:"updated_at"`
}

Webhook represents a webhook registered in the httpSMS API

type WebhookResponse added in v0.0.8 

type WebhookResponse ApiResponse[Webhook]

WebhookResponse is the response gotten with a webhook

type WebhookService added in v0.0.8 

type WebhookService service

WebhookService is the API client for the webhook endpoints

func (*WebhookService) Store added in v0.0.8 

func (service *WebhookService) Store(ctx context.Context, params *WebhookStoreParams) (*WebhookResponse, *Response, error)

Store adds a new webhook

type WebhookStoreParams added in v0.0.8 

type WebhookStoreParams struct {
	SigningKey   string   `json:"signing_key"`
	URL          string   `json:"url"`
	PhoneNumbers []string `json:"phone_numbers"`
	Events       []string `json:"events"`
}

WebhookStoreParams is the request payload for creating a webhook

Source Files

View all Source files

Directories

Path Synopsis
internal
helpers
stubs

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.