bulksms
Module bulksms
API
ballerinax/bulksms Ballerina library
Overview
This is a generated connector for BulkSMS API v1 OpenAPI Specification.
BulkSMS API provides capability to access you to submit and receive BulkSMS messages. You can also get
access to past messages and see your account profile. Dates are formatted according to ISO-8601, such as 1970-01-01T10:00:00+01:00
for 1st January 1970, 10AM UTC+1. It currently supports operations on messages, numbers, user profile, webhooks, and batch messages.
Prerequisites
Before using this connector in your Ballerina application, complete the following:
- Create bulkSMS account
- Obtaining tokens
- Provide the username and password for the Authentication. Follow this link for more detail
Quickstart
To use the bulkSMS connector in your Ballerina application, update the .bal file as follows:
Step 1 - Import connector
import ballerinax/bulksms;
Step 2 - Create a new connector instance
configurable http:CredentialsConfig & readonly auth = ?; bulksms:ClientConfig clientConfig = {auth : auth}; bulksms:Client baseClient = check new Client(clientConfig);
Step 3 - Invoke connector operation
- Invoking connector operations using the client
bulksms:Profile profile = check baseClient->getProfile();
- Use
bal run
command to compile and run the Ballerina program.
Clients
bulksms: Client
This is a generated connector for BulkSMS API v1 OpenAPI Specification.
BulkSMS API provides capability to access you to submit and receive BulkSMS messages. You can also get access to past messages and see your account profile. Dates are formatted according to ISO-8601, such as 1970-01-01T10:00:00+01:00
for 1st January 1970, 10AM UTC+1. It currently supports operations on messages, numbers, user profile, webhooks, and batch messages.
Constructor
Gets invoked to initialize the connector
.
The connector initialization requires setting the API credentials. Create an BulkSMS account and obtain tokens following this guide.
init (ConnectionConfig config, string serviceUrl)
- config ConnectionConfig - The configurations to be used when initializing the
connector
- serviceUrl string "https://api.bulksms.com/v1" - URL of the target service
listWebhooks
Lists webhooks
createWebhook
function createWebhook(WebhookEntry payload) returns Webhook|error
Creates a webhook
Parameters
- payload WebhookEntry - Contains the property values for your new webhook
getWebhookByID
Reads a webhook
Parameters
- id string - The
id
of the webhook
updateWebhook
function updateWebhook(string id, WebhookEntry payload) returns Webhook|error
Updates a webhook
Parameters
- id string - The
id
of the webhook
- payload WebhookEntry - Contains the new property values for the webhook
deleteWebhook
Deletes a webhook
Parameters
- id string - The
id
of the webhook
getProfile
Gets profile
retrieveMessages
Retrieves Messages
Parameters
- 'limit int? (default ()) - The maximum number of messages that are returned. The default is 1000. The value of
limit
is not a guarantee that a specific number of messages will be in the response, even if there are more messages available. Consider the case where you have 150 messages and you specifylimit=50
. It is possible that only 49 messages will be returned. The way to make sure that there are no more messages is to submit a new call using theid
filter field with the<
operator (described below).
- filter string? (default ()) - See the message filtering for more information.
- sortOrder string? (default ()) - The default value is DESCENDING If the
sortOrder
is DESCENDING, the newest messages be first in the result. ASCENDING places the oldest messages on top of the response.
sendBatchMessages
function sendBatchMessages(SubmissionEntry[] payload, int? deduplicationId, boolean autoUnicode, string? scheduleDate, string? scheduleDescription) returns Message[]|error
Sends batch messages
Parameters
- payload SubmissionEntry[] - Contains details of the message (or messages) that you want to send.
- deduplicationId int? (default ()) - Safeguards against the possibility of sending the same messages more than once. If a communication failure occurs during a submission, you cannot be sure that the submission was processed; therefore you would have to submit it again. When you post the retry, you must use the
deduplication-id
of the original post. The BulkSMS system uses this ID to check that the request was not previously processed. (If it was previously processed, the submission will succeed, and the behaviour will be indistinguishable to you from a non-duplicated submission). The ID expires after about 12 hours.
- autoUnicode boolean (default false) - Specifies how to deal with message text that contains characters not present in the GSM 03.38 character set. Messages that contain only GSM 03.38 characters are not affected by this setting. If the value is
true
then a message containing non-GSM 03.38 characters will be transmitted as a Unicode SMS (which is most likely more costly). Please note: whenauto-unicode
istrue
and the value of theencoding
property is specified asUNICODE
, the message will always be sent asUNICODE
. If the value isfalse
and theencoding
property isTEXT
then non-GSM 03.38 characters will be replaced by the?
character. When using this setting on the API, you should take case to ensure that your message is clean. Invisible unicode and unexpected characters could unintentionally convert an message toUNICODE
. A common mistake is to use the backtick character (`) which is unicode and will turn yourTEXT
message into aUNICODE
message. MISSING[`]
- scheduleDate string? (default ()) - Allows you to send a message in the future. An example value is
2019-02-18T13:00:00+02:00
. It encodes to2019-02-18T13%3A00%3A00%2B02%3A00
. Credits are deducted from your account immediately. Once submitted, scheduled messages cannot be changed or cancelled. The date can be a maximum of two years in the future. If the value is in the past, the message will be sent immediately. The date format requires you to supply an offset from UTC. You can decide to use the offset of your timezone, or maybe the zone of the recipient's location is more appropriate. If the destination is a group, the group members are determined at the time that you submit the message; not the time the message is scheduled to be sent.
- scheduleDescription string? (default ()) - A note that is stored together with a scheduled submission, which could be used to more easily identify the scheduled submission at a later date. The value of this field is ignored if the
schedule-date
is not provided. A value that is longer than 256 characters is truncated.
sendMessage
Sends message by simple GET or POST
Parameters
- to string - The phone number of the recipient.
- body string - The text you want to send.
- deduplicationId int? (default ()) - Refer to the
deduplication-id
parameter.
getSentMessages
Lists Related Messages
Parameters
- id string - The
id
of the sent message
Return Type
getMessage
Shows Message
Parameters
- id string - The
id
of the message you want to retrieve
listBlockedNumbers
function listBlockedNumbers(int? minId, int? 'limit) returns BlockedNumber|error
Lists blocked numbers
Parameters
- minId int? (default ()) - Records with an
id
that is greater or equal to min-id will be returned. The default value is0
. You can add 1 to an id that you previously retrieved, to return subsequent records.
- 'limit int? (default ()) - The maximum number of records to return. The default value is
10000
. The value cannot be greater than 10000.
Return Type
- BlockedNumber|error - A list of BlockedNumber objects
createBlockedNumber
function createBlockedNumber(PhoneNumber[] payload) returns Response|error
Creates a blocked number
Parameters
- payload PhoneNumber[] - Maximum size:
1000
items
Records
bulksms: BlockedNumber
Fields
- id int - A unique identifier that is assigned when the BlockedNumber is created.
- phoneNumber PhoneNumber - A phone number in E.164 format
bulksms: ClientHttp1Settings
Provides settings related to HTTP/1.x protocol.
Fields
- keepAlive KeepAlive(default http:KEEPALIVE_AUTO) - Specifies whether to reuse a connection for multiple requests
- chunking Chunking(default http:CHUNKING_AUTO) - The chunking behaviour of the request
- proxy ProxyConfig? - Proxy server related options
bulksms: ConnectionConfig
Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.
Fields
- auth CredentialsConfig - Configurations related to client authentication
- httpVersion HttpVersion(default http:HTTP_2_0) - The HTTP version understood by the client
- http1Settings ClientHttp1Settings? - Configurations related to HTTP/1.x protocol
- http2Settings ClientHttp2Settings? - Configurations related to HTTP/2 protocol
- timeout decimal(default 60) - The maximum time to wait (in seconds) for a response before closing the connection
- forwarded string(default "disable") - The choice of setting
forwarded
/x-forwarded
header
- poolConfig PoolConfiguration? - Configurations associated with request pooling
- cache CacheConfig? - HTTP caching related configurations
- compression Compression(default http:COMPRESSION_AUTO) - Specifies the way of handling compression (
accept-encoding
) header
- circuitBreaker CircuitBreakerConfig? - Configurations associated with the behaviour of the Circuit Breaker
- retryConfig RetryConfig? - Configurations associated with retrying
- responseLimits ResponseLimitConfigs? - Configurations associated with inbound response size limits
- secureSocket ClientSecureSocket? - SSL/TLS-related options
- proxy ProxyConfig? - Proxy server related options
- validation boolean(default true) - Enables the inbound payload validation functionality which provided by the constraint package. Enabled by default
bulksms: Error
See the errors page for more detail on what kind of errors you can get.
Fields
- 'type string - A URL to one of the error types.
- title string - A short description of the type
- status int - The HTTP status code
- detail string? - More information about why the error occurred.
bulksms: Message
Fields
- id string - A unique identifier that is assigned when the message is created.
- 'type string - The message direction
- 'from string? - The address part of the sender id
- to string - The phone number of the recipient
- body record {} - The content of the message
- encoding string? - The type of the content. See the
encoding
field for more information.
- protocolId int? - See the
protocolId
field for more information.
- messageClass int? - See the
messageClass
field for more information.
- numberOfParts int? - The number of parts. If this is a concatenated message, the number of parts will be more than 1. Note that this field does not have a value in the submission response.
- creditCost float? - The cost of the message (in credits). Note that this field does not have a value in the submission response.
- submission MessageSubmission? - Identifies the submission.
- status MessageStatus - The status of the message
- relatedSentMessageId string? - This field has a value only if the type is RECEIVED.
With SMS messages, it is not possible to link a reply directly with a specific sent message. However, if you specified
REPLIABLE
in thefrom
property, BulkSMS will link any reply to the most recent message sent to a given phone number. TherelatedSentMessageId
property keeps the information about this link. You can use this property to derive an implicit conversation from a set of messages.- If a received reply message has a
relatedSentMessageId
, you can use it to retrieve the last message that was sent before the reply was received. - If you have the
id
of the sent message and you want all the received messages that relate to it, you can use the List Related Messages Operation.
- If a received reply message has a
- userSuppliedId string? - This is the value you supplied in the
userSuppliedId
field. Has a value only if thetype
is SENT.
bulksms: MessageStatus
The status of the message
Fields
- id string - A concatenated value A.B where A is the
status.type
and B is thestatus.subtype
.
It there is no value forsubtype
then B takes string value"null"
(e.g."SENT.null"
).
- 'type string - ACCEPTED Message accepted for delivery. Only returned for initial message submissions. SCHEDULED Message accepted for delivery at a later date. Only returned for initial message submissions. SENT Message has been relayed away from our systems. DELIVERED Successfully delivered to phone. UNKNOWN Message is in an unknown state. FAILED Delivery failed.
- subtype string? - Has a value only if the
type
is FAILED. EXPIRED Delivery failed because message expired before delivery was possible. HANDSET_ERROR Delivery failed because of a problem related to the phone (e.g. message storage area full). BLOCKED Your account has been blocked from sending to this phone (e.g. recipient replied STOP to block communication). NOT_SENT Message delivery was not attempted (e.g. because we were not able to find a route for the supplied phone number).
bulksms: MessageSubmission
Identifies the submission.
Fields
- id string - A unique identity shared by all messages that were created from the same submission. This field should be ignored if the
type
is not SENT.
- date string - The date and time the submission was processed. If the
type
is RECEIVED, this field reflects the date and time the received message was processed.
bulksms: Profile
Represents a profile
Fields
- id string - profile ID
- username string - username of profile
- created string - Created data/time
- credits ProfileCredits - Credit Amount
- quota ProfileQuota - quota details
- originAddresses ProfileOriginaddresses? - Original Address
- company ProfileCompany? - company details
- commerce ProfileCommerce? - commerce profile details
bulksms: ProfileCommerce
commerce profile details
Fields
- bankPaymentReference string? - Bank payment detail reference
- address ProfileCommerceAddress? - Commerce address
bulksms: ProfileCommerceAddress
Commerce address
Fields
- street string[]? - Street
- city string? - City
- region string? - Region
- country string? - Country
- postalCode string? - Postal Code
bulksms: ProfileCompany
company details
Fields
- name string? - name of the company
- taxReference string? - tax reference
bulksms: ProfileCredits
Credit Amount
Fields
- balance float? - Credit balance
- 'limit int? - Credit limit
- isTransferAllowed boolean? - Indicates whether the transferring is allowed or not
bulksms: ProfileOriginaddresses
Original Address
Fields
- isFullControlAllowed boolean? - Indicates whether the full control is allowed or not
- allowed string[]? - An array of allowed details
bulksms: ProfileQuota
quota details
Fields
- size int - The setting that limits the number of messages you can send in a day.
- remaining int - The number of messages you can still send today.
bulksms: ProxyConfig
Proxy server configurations to be used with the HTTP client endpoint.
Fields
- host string(default "") - Host name of the proxy server
- port int(default 0) - Proxy server port
- userName string(default "") - Proxy server username
- password string(default "") - Proxy server password
bulksms: SubmissionEntry
An object that you use when posting messages.
Fields
- 'from SubmissionentryFrom? - Identifies the sender.
Instead of a structured object, you can supply a string value here.
If you do this, the
type
of the sender is derived to be either INTERNATIONAL or ALPHANUMERIC. If the value does not begin with a+
and it contains at least one character that is not a digit, the type is detected as ALPHANUMERIC. Otherwise, the type is detected as INTERNATIONAL.
- to SubmissionentryTo[] - Identifies the recipients
Instead of an array of structured objects, you can also provide a single object, a simple string or an array of strings.
If you supply a string, the
type
is taken as INTERNATIONAL.
- routingGroup string? - Allows you to choose routing. The default is STANDARD.
- encoding string? - Describes the content of the message body.
Typically this is TEXT, which is the default if no value is provided.
If you need to send characters that are not covered by the GSM 03.38 character set you will need to specify UNICODE.
If you want to send a sequence of bytes, you must use BINARY.
You can also or use the
auto-unicode
parameter of the Send Messages Operation. If you supply the value ofTEXT
whileauto-unicode
istrue
then your message may be converted toUNICODE
. If you supply a value other thanTEXT
for this property whileauto-unicode
istrue
then no automatic conversion will take place.
- longMessageMaxParts int? - The maximum number of message parts that can be used for a concatenated message.
The default is
3
.
- body string - The message content as described in the
encoding
. If theencoding
is BINARY, the body must contain only hexadecimal digits where one byte is represented as two digits. For example, if you want to send two bytes '0x05' and '0x1F', the message body must contain the text '051F'. The message content can also contain templates, read the body templates section for more information.
- userSuppliedId string? - Correlate the messages created from this submission to your data. The value can contain no more than 20 characters.
- protocolId string? - The TP-PID value from GSM 03.40[.750] §9.2.3.9.
You can provide either an integer value, or a mnemonic string.
If unspecified, this property defaults to
0
, representing the IMPLICIT value. Numeric values are listed below | Name | Value| |----- |------| | IMPLICIT | 00 | | SHORT_MESSAGE_TYPE_0 | 64 | | REPLACE_MESSAGE_1 | 65 | | REPLACE_MESSAGE_2 | 66 | | REPLACE_MESSAGE_3 | 67 | | REPLACE_MESSAGE_4 | 68 | | REPLACE_MESSAGE_5 | 69 | | REPLACE_MESSAGE_6 | 70 | | REPLACE_MESSAGE_7 | 71 | | RETURN_CALL | 95 | | ME_DOWNLOAD | 125 | | ME_DEPERSONALIZE | 126 | | SIM_DOWNLOAD | 127 |
- messageClass string? - The class of the message, as specified by §4 of the GSM 03.38 specification. You can provide either an integer value, or a mnemonic string. The default value is SIM_SPECIFIC. Numeric values are | Name | Value| |------|------| | FLASH_SMS | 0 | | ME_SPECIFIC | 1 | | SIM_SPECIFIC | 2 | | TE_SPECIFIC | 3 |
- deliveryReports string? - The type of delivery reports to request from the delivering network.
The default value is
ALL
. Please note that not all networks support delivery reports. ALL. All possible delivery reports ERRORS. Only error delivery reports NONE. No delivery reports
bulksms: SubmissionentryFrom
Identifies the sender.
Instead of a structured object, you can supply a string value here.
If you do this, the type
of the sender is derived to be either INTERNATIONAL or ALPHANUMERIC. If the value does not begin with a +
and it contains at least one character that is not a digit, the type is detected as ALPHANUMERIC. Otherwise, the type is detected as INTERNATIONAL.
Fields
- 'type string - The type of the sender id. If you want BulkSMS to collect replies to this message on your behalf, specify the type as REPLIABLE. If the recipient is in a country where BulkSMS does not have a local reply number, the reply may incur costs that are more expensive than sending a local SMS in that country. If you operate a service from a shortcode in a locale that allows messaging from such a shortcode, you can specify SHORTCODE for the type.
- address string? - The address of the sender id.
The validation for this field depends on the value of the
type
. INTERNATIONAL can start with+
. It has a maximum length of 15 digits, and has to be longer than 6 digits. ALPHANUMERIC has a maximum length of 11 characters. SHORTCODE has a maximum length of 6 digits. REPLIABLE should not specify a value here.
bulksms: SubmissionentryTo
Fields
- 'type string? - Type of the recipient. The default value is INTERNATIONAL.
- address string? - The phone number of the recipient. It must be supplied if the
type
is INTERNATIONAL
- name string? - The name of a group in your phonebook. A value can be given if the
type
is GROUP.
- id string? - The id of a group in your phonebook. A value can be given if the
type
is GROUP.
- fields string[]? - Custom fields that can be used in the message body. A value can be given if the
type
is INTERNATIONAL Read the body templates section for more information.
bulksms: Webhook
Represents a webhook
Fields
- id decimal? - Webhook ID
- name string? - Webhook name
- url string? - Webhook URL
- contactEmailAddress string? - Contact email address
- triggerScope string? - Trigger scope details
- active boolean? - Indicates whether the webhook is active or not
- onWebApp boolean? - Indicates whether it is on web app or not
bulksms: WebhookEntry
Fields
- name string - A text identifier for the webhook. More than one webhook cannot have the same name.
- contactEmailAddress string? - The email address to which emails will be sent if there are problem with invoking the webhook.
The value must be a valid email address.
If this value is
null
, no email will be sent. It isnull
by default.
- triggerScope string - Specifies when the webhook will be triggered.
Please note the values are case sensitive.
If the value is
SENT
, the webhook will be called when a status update becomes available for a message you sent (i.e. a mobile terminating (MT) message). If the value isRECEIVED
, the webhook will be called when a message is received (i.e. a mobile originating (MO) message). Note that this field forces you to create two separate webhook entries if you want to collect all messages. However, you can use the sameurl
for both webhooks if you want.
- invokeOption string? - Specifies how to invoke your webhook.
If the value is
ONE
the array POSTed to your webhook will contain no more than a single message. Use this option if your webhook logic is unable to handle more than one messages at a time. If the value isMANY
the array POSTed to your webhook can contain up to 10 messages. This is the recommended option. The number of calls made to your webhook would be less and this will speed up your total processing time. If your webhook fails for an invoke that has more than one message, each message in the array will automatically be retried one at a time. This value defaults toONE
- but it is recommended that you set this property toMANY
.
- active boolean? - Indicates whether you want the webhook activated.
If the value is
true
, the webhook at the givenurl
will be invoked with an empty array ([]
) as part of the validation process. If the webhook responds with a2xx
status code, the submission is accepted; if not the webhook is not created (or updated). If the value isfalse
the webhook will be inactive, and it will not be invoked when messages areSENT
orRECEIVED
. The default value istrue
.
- onWebApp boolean? - Indicates whether you want to show this webhook on the Web App.
Webhooks shown there can be updated by the user that use the public Web site.
The default value is
true
.
String types
bulksms: PhoneNumber
PhoneNumber
A phone number in E.164 format
Import
import ballerinax/bulksms;
Metadata
Released date: over 1 year ago
Version: 1.5.1
License: Apache-2.0
Compatibility
Platform: any
Ballerina version: 2201.4.1
GraalVM compatible: Yes
Pull count
Total: 2
Current verison: 1
Weekly downloads
Keywords
Communication/Call & SMS
Cost/Paid
Contributors
Dependencies