The MultiTXT API provides a number of endpoints for building powerful two-way messaging applications. The Messages API provides access to three main resources:
- Messages - Messages delivered from an application to a handset.
- Delivery Reports - Real time reports on the delivery status of a message. As a message is processed, it's status may change several times before it is finally delivered to a handset.
- Replies - Messages sent from a handset to an application. These messages are typically a reply to a previously sent message.
Base URI
The API uses the following base URI:
https://api.multitxt.co.nz
Note: The use of the HTTPS protocol is required.
Authentication
All requests to the MultiTXT API must be authenticated, this is done using Basic Authentication.
Basic Authentication
Every request requires an Authorization header in the following format:
Authorization: Basic Base64(api_key:api_secret)
Where the header consists of the Basic keyword followed by your Basic Authentication api_key and api_secret that you have been supplied by support, seperated with a colon (:) which is then Base64 encoded.
Example request with Basic Authentication
POST /v1/messages HTTP/1.1
Host: api.multitxt.co.nz
Accept: application/json
Content-Type: application/json
Authorization: Basic dGhpc2lzYWtleTp0aGlzaXNhc2VjcmV0Zm9ybW1iYXNpY2F1dGhyZXN0YXBp
{
"messages": [
{
"content": "Hello World",
"destination_number": "+64216457256",
"format": "SMS"
}
]
}
Note: spaces are used as indentation in the body of the above request.
HMAC Authentication
Every request requires an Authorization header in the following formats:
For a request with a request body:
Authorization: hmac username="<API KEY>", algorithm="hmac-sha1", headers="Date Content-MD5 request-line", signature="<SIGNATURE>"
For a request without a request body:
Authorization: hmac username="<API KEY>", algorithm="hmac-sha1", headers="Date request-line", signature="<SIGNATURE>"
To create this header
Step 1
Add a Date header to the request using the current date time in RFC7231 Section 7.1.1.2 format
Step 2
If the request has a body, add a header called Content-MD5 where the value of this header is an MD5 hash of the request body, otherwise this header is not required
Step 3
Create a signing string by concatenating the Date header, the Content-MD5 header (if set) and the request line with line breaks:
Date: Sat, 30 Jul 2016 05:13:23 GMT\nContent-MD5: 10fd4feab20d38432480c07301e49616\nPOST /v1/messages HTTP/1.1
or
Date: Sat, 30 Jul 2016 05:13:23 GMT\nGET /v1/messages/404b941b-2a29-469f-b114-9ea3e16bbe18 HTTP/1.1
Step 4
Create a SHA1 HMAC hash using the signing string and the secret key (both converted to bytes using UTF-8) HMAC-SHA1(signing string, secret)
Step 5
Base64 encode the HMAC hash and include it as the signature in the Authorization header
Example request with body
POST /v1/messages HTTP/1.1
Host: api.multitxt.co.nz
Accept: application/json
Content-Type: application/json
Date: Sat, 30 Jul 2016 05:18:52 GMT
Authorization: hmac username="uCXUdoogNfCsehEClbO2", algorithm="hmac-sha1", headers="Date Content-MD5 request-line", signature="Ia4G5lkhH/3NDYpix+8ZHUnp6bA="
Content-MD5: 5407644fa83bec240dede971307e0cad
Content-Length: 133
{
"messages": [
{
"content": "Hello World",
"destination_number": "+64216457256",
"format": "SMS"
}
]
}
Note: spaces are used as indentation in the body of the above request.
Example request without body
GET /v1/messages/404b941b-2a29-469f-b114-9ea3e16bbe18 HTTP/1.1 Host: api.multitxt.co.nz Accept: application/json Date: Sat, 30 Jul 2016 05:18:52 GMT Authorization: hmac username="uCXUdoogNfCsehEClbO2", algorithm="hmac-sha1", headers="Date request-line", signature="NTUwMjUwNTVmZGYzZTIxODMyYjc1ZmM3M2EwZWQ1NzA3NzA4ZTZjNw=="
Contents
Messages
Messages operations.
Send messages
POST /v1/messages
Submit one or more (up to 100 per request) SMS messages for delivery.
The most basic message has the following structure:
{
"messages": [
{
"content": "My first message!",
"destination_number": "+64216457256"
}
]
}
More advanced delivery features can be specified by setting the following properties in a message:
-
callback_urlA URL can be included with each message to which Webhooks will be pushed to via a HTTP POST request. Webhooks will be sent if and when the status of the message changes as it is processed (if the delivery report property of the request is set totrue) and when replies are received. Specifying a callback URL is optional. -
contentThe content of the message. This can be a Unicode string, up to 5,000 characters long. Message content is required. -
delivery_reportDelivery reports can be requested with each message. If delivery reports are requested, a webhook will be submitted to thecallback_urlproperty specified for the message (or to the webhooks specified for the account) every time the status of the message changes as it is processed. Delivery reports are optional and by default will not be requested. -
destination_numberThe destination number the message should be delivered to. This should be specified in E.164 international format. For information on E.164, please refer to http://en.wikipedia.org/wiki/E.164. A destination number is required. -
formatThe format specifies which format the message will be sent as,SMS(text message). -
source_number_typeIf a source number is specified, the type of source number may also be specified. This is recommended when using a source address type that is not an internationally formatted number, available options areINTERNATIONALorSHORTCODE. Specifying a source number type is only valid when thesource_numberparameter is specified and is optional. If a source number is specified and no source number type is specified, the source number type will be inferred from the source number, however this may be inaccurate. -
source_number[optional] Specify a source number to be used. Refer to the section below for more information on source numbers. ⚠️ The number or sender ID must be registered to your account (from 1-Mar-2024).
Source number (sender ID)
There are several options for the number or sender ID that will show as the source of an outbound message. Some things to note:
• If you do not specify a source number, the message will be sent with the default number for your account.
• The default may be a number you have purchased from us - such as a dedicated number, a 10-digit longcode or toll-free number (US/CA), or a shortcode. Log into the web portal to manage your numbers.
• If your account has multiple numbers, you can specify which source number to use in the request.
• If your account does not have a number, your message may be sent using our shared number pool (in certain countries only)
• Alpha tag: In some countries (AU, GB, some others), you may be able to send using an alpha tag - text that represents your brand of business. Before using an alpha tag, you must register it in the Numbers section of the web portal.
• Other numbers: You may use numbers that you own as the source number, but you must register them in the Numbers section of the web portal to confirm you have a right to use the number. If you need to register a large number of source numbers/sender IDs, consider using our Source Address API
⚠️ If you specify a source_number that is not registered to your account, the message may fail to send, or may be sent with an alternative number.
-
scheduledA message can be scheduled for delivery in the future by setting the scheduled property. The scheduled property expects a date time specified in ISO 8601 format. The scheduled time must be provided in UTC and is optional. If no scheduled property is set, the message will be delivered immediately. -
message_expiry_timestampA message expiry timestamp can be provided to specify the latest time at which the message should be delivered. If the message cannot be delivered before the specified message expiry timestamp elapses, the message will be discarded. Specifying a message expiry timestamp is optional. -
metadataMetadata can be included with the message which will then be included with any delivery reports or replies matched to the message. This can be used to create powerful two-way messaging applications without having to store persistent data in the application. Up to 10 key / value metadata data pairs can be specified in a message. Each key can be up to 100 characters long, and each value up to 256 characters long. Specifying metadata for a message is optional.
The response body of a successful POST request to the messages endpoint will include a messages property which contains a list of all messages submitted. The list of messages submitted will reflect the list of messages included in the request, but each message will also contain two new properties, message_id and status. The returned message ID will be a 36 character UUID which can be used to check the status of the message via the Get Message Status endpoint.
Sending from sub-accounts
Using API keys at the parent account level, you can send messages on behalf of a sub-account. To do this include a header key Account with the sub-account ID as the value. For example:
Example request with Sending from sub-accounts
POST /v1/messages HTTP/1.1
Host: api.messagemedia.com
Accept: application/json
Content-Type: application/json
Authorization: Basic dGhpc2lzYWtleTp0aGlzaXNhc2VjcmV0Zm9ybW1iYXNpY2F1dGhyZXN0YXBp
Account: SubAccount
{
"messages": [
{
"content": "Hello World",
"destination_number": "+61491570156",
“delivery_report”: true
}
]
}
Note: when sending multiple messages in a request, all messages must be valid for the request to be successful. If any messages in the request are invalid, no messages will be sent.
Authentication: basic_auth or hmac_auth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Accept |
header | string | No | e.g. application/json |
Request body
Optional.
Fields
| Field | Type | Required | Description |
|---|---|---|---|
messages |
array of object | Yes | |
messages[].callback_url |
string | No | URL replies and delivery reports to this message will be pushed to |
messages[].content |
string | No | Content of the message |
messages[].destination_number |
string | No | Destination number of the message |
messages[].delivery_report |
boolean | No | Request a delivery report for this message |
messages[].format |
array of enum: SMS | No | Format of message. |
messages[].message_expiry_timestamp |
string | No | Date time after which the message expires and will not be sent |
messages[].metadata |
object | No | Metadata for the message specified as a set of key value pairs, each key can be up to 100 characters long and each value can be up to 256 characters long `` { "myKey": "myValue", "anotherKey": "anotherValue" } `` |
messages[].scheduled |
string | No | Scheduled delivery date time of the message |
messages[].source_number |
string | No | |
messages[].source_number_type |
enum: INTERNATIONAL, SHORTCODE | No | Type of source address specified, this can be INTERNATIONAL or SHORTCODE |
messages[].message_id |
string | No | Unique ID of the original message |
messages[].status |
enum: enroute, submitted, delivered, expired, rejected, undeliverable, queued, processed, cancelled, scheduled, failed | No | The status of the message |
Example
{
"messages": [
{
"callback_url": "https://my.callback.url.com",
"content": "My first message",
"destination_number": "+64216457256",
"delivery_report": true,
"format": "SMS",
"message_expiry_timestamp": "2016-11-03T11:49:02.807Z",
"metadata": {
"myKey": "myValue",
"anotherKey": "anotherValue"
},
"scheduled": "2016-11-03T11:49:02.807Z",
"source_number": "+64216567245",
"source_number_type": "INTERNATIONAL"
},
{
"callback_url": "https://my.callback.url.com",
"content": "My second message",
"destination_number": "+64216457256",
"delivery_report": true,
"format": "SMS",
"message_expiry_timestamp": "2016-11-03T11:49:02.807Z",
"metadata": {
"myKey": "myValue",
"anotherKey": "anotherValue"
},
"scheduled": "2016-11-03T11:49:02.807Z",
"source_number": "+64216567245",
"source_number_type": "INTERNATIONAL"
}
]
}
Responses
202 — Messages were accepted for processing
| Field | Type | Required | Description |
|---|---|---|---|
messages |
array of object & string & enum: enroute, submitted, delivered, expired, rejected, undeliverable, queued, processed, cancelled, scheduled, failed | No | |
messages[].callback_url |
string | No | URL replies and delivery reports to this message will be pushed to |
messages[].content |
string | No | Content of the message |
messages[].destination_number |
string | No | Destination number of the message |
messages[].delivery_report |
boolean | No | Request a delivery report for this message |
messages[].format |
array of enum: SMS | No | Format of message. |
messages[].message_expiry_timestamp |
string | No | Date time after which the message expires and will not be sent |
messages[].metadata |
object | No | Metadata for the message specified as a set of key value pairs, each key can be up to 100 characters long and each value can be up to 256 characters long `` { "myKey": "myValue", "anotherKey": "anotherValue" } `` |
messages[].scheduled |
string | No | Scheduled delivery date time of the message |
messages[].source_number |
string | No | |
messages[].source_number_type |
enum: INTERNATIONAL, SHORTCODE | No | Type of source address specified, this can be INTERNATIONAL or SHORTCODE |
Example:
{
"messages": [
{
"message_id": "04fe9a97-a579-43c5-bb1a-58ed29bf0a6a",
"callback_url": "https://my.url.com",
"status": "delivered",
"content": "My first message",
"destination_number": "+64216457256",
"delivery_report": true,
"format": "SMS",
"message_expiry_timestamp": "2016-11-03T11:49:02.807Z",
"metadata": {
"myKey": "myValue",
"anotherKey": "anotherValue"
},
"scheduled": "2016-11-03T11:49:02.807Z",
"source_number": "+64216567245",
"source_number_type": "INTERNATIONAL"
}
]
}
400 — Request was invalid
| Field | Type | Required | Description |
|---|---|---|---|
message |
string | No |
Example:
{
"message": "Request failed to parse correctly. Please ensure input is valid and try again."
}
403 — Unauthorised
| Field | Type | Required | Description |
|---|---|---|---|
message |
string | No |
Example:
{
"message": "Invalid authentication credentials"
}
Example request
curl -X POST "https://api.multitxt.co.nz/v1/messages" \
-H "Accept: application/json" \
-H "Authorization: Basic <base64(api_key:api_secret)>" \
-H "Content-Type: application/json" \
-d '{"messages":[{"callback_url":"https://my.callback.url.com","content":"My first message","destination_number":"+64216457256","delivery_report":true,"format":"SMS","message_expiry_timestamp":"2016-11-03T11:49:02.807Z","metadata":{"myKey":"myValue","anotherKey":"anotherValue"},"scheduled":"2016-11-03T11:49:02.807Z","source_number":"+64216567245","source_number_type":"INTERNATIONAL"},{"callback_url":"https://my.callback.url.com","content":"My second message","destination_number":"+64216457256","delivery_report":true,"format":"SMS","message_expiry_timestamp":"2016-11-03T11:49:02.807Z","metadata":{"myKey":"myValue","anotherKey":"anotherValue"},"scheduled":"2016-11-03T11:49:02.807Z","source_number":"+64216567245","source_number_type":"INTERNATIONAL"}]}'
Get message status
GET /v1/messages/{messageId}
Retrieve the current status of a message using the message ID returned in the send messages end point.
A successful request to the get message status endpoint will return a response body as follows:
{
"format": "SMS",
"content": "My first message!",
"metadata": {
"myKey": "myValue",
"anotherKey": "anotherValue"
},
"message_id": "877c19ef-fa2e-4cec-827a-e1df9b5509f7",
"callback_url": "https://my.callback.url.com",
"delivery_report": true,
"destination_number": "+64216457256",
"scheduled": "2016-11-03T11:49:02.807Z",
"source_number": "+64216567245",
"source_number_type": "INTERNATIONAL",
"message_expiry_timestamp": "2016-11-03T11:49:02.807Z",
"status": "enroute"
}
The status property of the response indicates the current status of the message. See the Webhooks section of this documentation for more information on message statues. The expiry date for getting an entity is 45 days.
Note: If an invalid or non existent message ID parameter is specified in the request, then a HTTP 404 Not Found response will be returned
Authentication: basic_auth or hmac_auth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
messageId |
path | string | Yes | |
Accept |
header | string | No | e.g. application/json |
Responses
200 — The submitted message including the status of the message
| Field | Type | Required | Description |
|---|---|---|---|
callback_url |
string | No | URL replies and delivery reports to this message will be pushed to |
content |
string | No | Content of the message |
destination_number |
string | No | Destination number of the message |
delivery_report |
boolean | No | Request a delivery report for this message |
format |
enum: SMS | No | Format of message. |
message_expiry_timestamp |
string | No | Date time after which the message expires and will not be sent |
metadata |
object | No | Metadata for the message specified as a set of key value pairs, each key can be up to 100 characters long and each value can be up to 256 characters long `` { "myKey": "myValue", "anotherKey": "anotherValue" } `` |
scheduled |
string | No | Scheduled delivery date time of the message |
source_number |
string | No | |
source_number_type |
enum: INTERNATIONAL, SHORTCODE | No | Type of source address specified, this can be INTERNATIONAL or SHORTCODE |
message_id |
string | No | Unique ID of this message |
status |
enum: enroute, submitted, delivered, expired, rejected, undeliverable, queued, processed, cancelled, scheduled, failed | No | The status of the message |
Example:
{
"format": "SMS",
"content": "My first message!",
"metadata": {
"key1": "value1",
"key2": "value2"
},
"message_id": "877c19ef-fa2e-4cec-827a-e1df9b5509f7",
"callback_url": "https://my.callback.url.com",
"delivery_report": true,
"destination_number": "+64216457256",
"scheduled": "2016-11-03T11:49:02.807Z",
"source_number": "+64216567245",
"source_number_type": "INTERNATIONAL",
"message_expiry_timestamp": "2016-11-03T11:49:02.807Z",
"status": "enroute"
}
403 — Unauthorised
| Field | Type | Required | Description |
|---|---|---|---|
message |
string | No |
Example:
{
"message": "Invalid authentication credentials"
}
404 — Resource not found
| Field | Type | Required | Description |
|---|---|---|---|
message |
string | No |
Example:
{
"message": "Resource not found"
}
Example request
curl -X GET "https://api.multitxt.co.nz/v1/messages/{messageId}" \
-H "Accept: application/json" \
-H "Authorization: Basic <base64(api_key:api_secret)>"
Cancel scheduled message
PUT /v1/messages/{messageId}
Cancel a scheduled message that has not yet been delivered.
A scheduled message can be cancelled by updating the status of a message from scheduled to cancelled. This is done by submitting a PUT request to the messages endpoint using the message ID as a parameter (the same endpoint used above to retrieve the status of a message).
The body of the request simply needs to contain a status property with the value set to cancelled. The expiry date for getting an entity is 45 days.
{
"status": "cancelled"
}
Note: Only messages with a status of scheduled can be cancelled. If an invalid or non existent message ID parameter is specified in the request, then a HTTP 404 Not Found response will be returned
Authentication: basic_auth or hmac_auth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
messageId |
path | string | Yes | |
Accept |
header | string | No | e.g. application/json |
Request body
Optional.
Fields
| Field | Type | Required | Description |
|---|---|---|---|
status |
enum: cancelled | Yes | Must be set to cancelled. |
Example
{
"status": "cancelled"
}
Responses
200 — Message status updated successfully
400 — Bad request
| Field | Type | Required | Description |
|---|---|---|---|
message |
string | No |
Example:
{
"message": "Message is not currently scheduled"
}
403 — Unauthorised
| Field | Type | Required | Description |
|---|---|---|---|
message |
string | No |
Example:
{
"message": "Invalid authentication credentials"
}
404 — Resource not found
| Field | Type | Required | Description |
|---|---|---|---|
message |
string | No |
Example:
{
"message": "Resource not found"
}
Example request
curl -X PUT "https://api.multitxt.co.nz/v1/messages/{messageId}" \
-H "Accept: application/json" \
-H "Authorization: Basic <base64(api_key:api_secret)>" \
-H "Content-Type: application/json" \
-d '{"status":"cancelled"}'
Webhooks
The Webhooks Management API allows you to manage your webhooks configuration. You can subscribe to one or several events, retrieve the webhooks, update them or even delete them if needed.
Retrieve Webhook
GET /v1/webhooks/messages
Retrieve all the webhooks created for the connected account. A successful request to the retrieve webhook endpoint will return a response body as follows:
{
"page": 0,
"pageSize": 100,
"pageData": [
{
"url": "https://webhook.com",
"method": "POST",
"id": "8805c9d8-bef7-41c7-906a-69ede93aa024",
"encoding": "JSON",
"events": [
"RECEIVED_SMS"
],
"headers": {},
"template": "{\"id\":\"$mtId\", \"status\":\"$statusCode\"}",
"read_timeout": 5000,
"retries": 3,
"retry_delay": 30
}
]
}
Note: Response 400 is returned when the page query parameter is not valid or the pageSize query parameter is not valid.
Authentication: basic_auth or hmac_auth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
page |
query | string | No | |
pageSize |
query | string | No |
Responses
200 — OK
400 — Unexpected error in API call. See HTTP response body for details.
Example:
{
"message": "Something went wrong. Please try again later."
}
Example request
curl -X GET "https://api.multitxt.co.nz/v1/webhooks/messages?page='0'&pageSize='10'" \ -H "Accept: application/json" \ -H "Authorization: Basic <base64(api_key:api_secret)>"
Create Webhook
POST /v1/webhooks/messages
Create a webhook for one or more of the specified events.
A webhook would typically have the following structure:
{
"url": "http://webhook.com",
"method": "POST",
"encoding": "JSON",
"headers": {
"Account": "DeveloperPortal7000"
},
"events": [
"RECEIVED_SMS"
],
"template": "{\"id\":\"$mtId\}",
"read_timeout": 5000,
"retries": 3,
"retry_delay": 30
}
A valid webhook must consist of the following properties:
-
urlThe configured URL which will trigger the webhook when a selected event occurs. -
methodThe methods to map CRUD (create, retrieve, update, delete) operations to HTTP requests. -
encodingWebhooks can be delivered using different content types. You can choose fromJSON,FORM_ENCODEDorXML. This will automatically add the Content-Type header for you so you don't have to add it again in theheadersproperty. -
headersHTTP header fields which provide required information about the request or response, or about the object sent in the message body. This should NOT include theContent-Typeheader. -
eventsEvent or events that will trigger the webhook. At least one event should be present. -
templateThe structure of the payload that will be returned. You can format this in JSON or XML. -
read_timeout(Optional) The read timeout for the call to the Webhook in milliseconds. Set to 20000 by default, max 60000. -
retries(Optional) The number of times the Webhook request should retry. Set to 0 by default, max 5. -
retry_delay(Optional) The delay period between retries in seconds. Minimum of 5, max 60
Types of Events
You can select all of the events (listed below) or combine them in whatever way you like but atleast one event must be used. Otherwise, the webhook won't be created.
A webhook will be triggered when any one or more of the events occur:
+ SMS
+ `RECEIVED_SMS` Receive an SMS + `OPT_OUT_SMS` Opt-out occured
+ MMS
+ `RECEIVED_MMS` Receive an MMS
+ DR (Delivery Reports)
+ `ENROUTE_DR` Message is enroute + `EXPIRED_DR` Message has expired + `REJECTED_DR` Message is rejected + `FAILED_DR` Message has failed + `DELIVERED_DR` Message is delivered + `SUBMITTED_DR` Message is submitted
Template Parameters
You can choose what to include in the data that will be sent as the payload via the Webhook. It's upto you to choose what format you would like the payload to be returned. You can choose between JSON or XML. Keep in my mind, if you've chosen JSON as the format, you must escape the JSON in the template value (see example above).
The table illustrates a list of all the parameters that can be included in the template and which event types it can be applied to.
| Data | Parameter Name | Example | Event Type |
|---|---|---|---|
| Service Type | $type | SMS |
DR MO MO MMS
|
| Message ID | $mtId, $messageId | 877c19ef-fa2e-4cec-827a-e1df9b5509f7 |
DR MO MO MMS
|
| Delivery Report ID | $drId, $reportId | 01e1fa0a-6e27-4945-9cdb-18644b4de043 |
DR |
| Reply ID | $moId, $replyId | a175e797-2b54-468b-9850-41a3eab32f74 |
MO MO MMS
|
| Account ID | $accountId | DeveloperPortal7000 |
DR MO MO MMS
|
| Message Timestamp | $submittedTimestamp | 2016-12-07T08:43:00.850Z |
DR MO MO MMS
|
| Provider Timestamp | $receivedTimestamp | 2016-12-07T08:44:00.850Z |
DR MO MO MMS
|
| Message Status | $status | enroute |
DR |
| Status Code | $statusCode | 200 |
DR |
| External Metadata | $metadata.get('key') | name |
DR MO MO MMS
|
| Source Address | $sourceAddress | +61491570156 |
DR MO MO MMS
|
| Destination Address | $destinationAddress | +61491593156 |
MO MO MMS
|
| Message Content | $mtContent, $messageContent | Hi John |
DR MO MO MMS
|
| Reply Content | $moContent, $replyContent | Hello Jane |
MO MO MMS
|
| Retry Count | $retryCount | 1 |
DR MO MO MMS
|
Note: A 400 response will be returned if the url is invalid, the events, encoding or method is null or the headers has a Content-Type attribute.
Message Statuses
Delivery Reports indicate message status. A message can have one of the following statuses:
-
enroute: Message has been received by the gateway and is being processed (or waiting to be processed). -
submitted: Message has been submitted to a provider/carrier for delivery. -
delivered: Message delivery has been confirmed by the provider, including to the handset (where possible). -
expired: The message has expired. -
rejected: The message will not be delivered - permanent failure. Reasons may include usage limit exceeded, insufficient credit, number blocked, or content filtered -
failed: The message has failed. Reasons may include no active routes to destination or undeliverable by downstream provider.
Message Status Codes
Status codes provide more granular insight into a message's status. A message can have one of the following status codes:
-
101: Message being processed by the gateway. -
102: Message is being rerouted to a different provider after failing via the first provider. -
151: Message held for screening. -
200: Message submitted to downstream provider for delivery. -
210: Message accepted by downstream provider. -
211: Message is enroute for delivery by provider. -
212: Message submitted. Delivery pending. -
213: Message scheduled for delivery by downstream provider. -
220: Message delivered. -
221: Message delivered to the handset. -
320: Message validity period has expired (prior to submission). -
401: Message validity period has expired (before delivery). -
301: Usage threshold reached. Message discarded. -
302: Destination address blocked. Message discarded. -
303: Source address blocked. Message discarded. -
304: Message dropped. Contact support. -
305: Message discarded due to duplicate detection. -
402: Message rejected by downstream provider. -
403: Message skipped by downstream provider. -
410: Invalid source address. -
411: Invalid destination address. -
412: Destination address blocked. -
413: SMS service unavailable on destination. -
414: Destination unreachable. -
330: Gateway failure. -
331: Message discarded. -
332: No available route to destination. -
333: Source address unsupported for this destination. -
400: Message failed; undeliverable. -
405: Message cancelled or deleted by provider.
Authentication: basic_auth or hmac_auth
Request body
Optional.
Example
{
"url": "http://webhook.com",
"method": "POST",
"encoding": "JSON",
"headers": {
"Account": "DeveloperPortal7000"
},
"events": [
"ENROUTE_DR",
"DELIVERED_DR"
],
"template": "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}",
"read_timeout": 5000,
"retries": 3,
"retry_delay": 30
}
Responses
201 — Webhook successfully created
Example:
{
"id": "6e2c61df-d30a-4555-82a5-0e79822d8f53",
"url": "http://myurl.com",
"method": "POST",
"encoding": "JSON",
"headers": {
"Account": "DeveloperPortal7000"
},
"events": [
"ENROUTE_DR",
"DELIVERED_DR"
],
"template": "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}",
"read_timeout": 5000,
"retries": 3,
"retry_delay": 30
}
400 — Request was invalid
Example:
{
"message": "Something went wrong. Please try again later."
}
409 — Duplicate webhook
Example:
{
"message": "A webhook with the given url and method already exists."
}
Example request
curl -X POST "https://api.multitxt.co.nz/v1/webhooks/messages" \
-H "Accept: application/json" \
-H "Authorization: Basic <base64(api_key:api_secret)>" \
-H "Content-Type: application/json" \
-d '{"url":"http://webhook.com","method":"POST","encoding":"JSON","headers":{"Account":"DeveloperPortal7000"},"events":["ENROUTE_DR","DELIVERED_DR"],"template":"{\"id\":\"$mtId\",\"status\":\"$statusCode\"}","read_timeout":5000,"retries":3,"retry_delay":30}'
Update Webhook
PATCH /v1/webhooks/messages/{webhookId}
Update a webhook. You can update individual attributes or all of them by submitting a PATCH request to the /webhooks/messages endpoint (the same endpoint used above to delete a webhook)
A successful request to the retrieve webhook endpoint will return a response body as follows:
{
"url": "https://webhook.com",
"method": "POST",
"id": "04442623-0961-464e-9cbc-ec50804e0413",
"encoding": "JSON",
"events": [
"RECEIVED_SMS"
],
"headers": {},
"template": "{\"id\":\"$mtId\", \"status\":\"$statusCode\"}"
}
Note: Only pre-created webhooks can be deleted. If an invalid or non existent webhook ID parameter is specified in the request, then a HTTP 404 Not Found response will be returned.
Authentication: basic_auth or hmac_auth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
webhookId |
path | string | Yes |
Request body
Optional.
Example
{
"url": "https://myurl.com",
"method": "POST",
"encoding": "FORM_ENCODED",
"events": [
"ENROUTE_DR"
],
"template": "{\"id\":\"$mtId\", \"status\":\"$statusCode\"}",
"read_timeout": 5000,
"retries": 3,
"retry_delay": 30
}
Responses
200 — Webhook updated successfully
400 — Unexpected error in API call. See HTTP response body for details.
Example:
{
"message": "Something went wrong. Please try again later."
}
404 — Webhook not found
Example request
curl -X PATCH "https://api.multitxt.co.nz/v1/webhooks/messages/a7f11bb0-f299-4861-a5ca-9b29d04bc5ad" \
-H "Accept: application/json" \
-H "Authorization: Basic <base64(api_key:api_secret)>" \
-H "Content-Type: application/json" \
-d '{"url":"https://myurl.com","method":"POST","encoding":"FORM_ENCODED","events":["ENROUTE_DR"],"template":"{\"id\":\"$mtId\", \"status\":\"$statusCode\"}","read_timeout":5000,"retries":3,"retry_delay":30}'
Delete Webhook
DELETE /v1/webhooks/messages/{webhookId}
Delete a webhook that was previously created for the connected account. A webhook can be cancelled by appending the UUID of the webhook to the endpoint and submitting a DELETE request to the /webhooks/messages endpoint.
A successful request to the retrieve webhook endpoint will return a null response.
Note: Only pre-created webhooks can be deleted. If an invalid or non existent webhook ID parameter is specified in the request, then a HTTP 404 Not Found response will be returned.
Authentication: basic_auth or hmac_auth
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
webhookId |
path | string | Yes |
Responses
204 — Webhook deleted successfully
404 — Webhook not found
Example request
curl -X DELETE "https://api.multitxt.co.nz/v1/webhooks/messages/a7f11bb0-f299-4861-a5ca-9b29d04bc5ad" \ -H "Accept: application/json" \ -H "Authorization: Basic <base64(api_key:api_secret)>"