SMS¶
Sending¶
To send an SMS message it is required to call POST /sms/messages sending message parameters in the body with the authorization data in the header.
Request parameters¶
Query-params:
| Parameter | Data type | Description |
|---|---|---|
| includeSegmentId (optional) |
boolean | If true, then the response for each will also indicate an array of identifiers for each message segment. False by default. |
| shortenUrl (optional) |
boolean | Flag that shortens the length of the link: if true, then the link will be shortened. False by default. |
Body:
| Parameter | Data type | Description |
|---|---|---|
| messages | array[Message] | The array of Message objects |
Message¶
| Parameter | Data type | Description |
|---|---|---|
| from | string | The sender’s name. Up to 11 Latin characters or 15 digits |
| to | string | Phone number in the international format in accordance with E. 164 standard |
| text | string | The message text |
| validity (optional) |
integer | Lifetime of the message in seconds Minimum value: 1 Maximum value: 259200, 3 days Default value: 172800, 2 days |
| priority (optional) |
priority | Message priority level. Between 0 and 3, where: 0 - low priority 3 - highest priority 0 - default priority level |
| callbackUrl (optional) |
string | URL the system will send notifications on the message status changes to. Any valid HTTP or HTTPS URL |
| options (optional) |
object | An object of data external systems need while receiving message statuses Any “key” array: {“key1”: “value1”,“key2”: “value2” } |
Request example¶
curl -X POST \
-H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
-H 'Content-Type: application/json' \
-d '{
"messages": [
{
"from": "MyCompany",
"to": "79034567890",
"text": "Code: 1234"
}
]
}' https://api.devino.online/sms/messages
Response example¶
{
"result": [
{
"code": "OK",
"messageId": "3482512350952730368"
}
]
}
Response parameters¶
| Parameter | Data type | Description |
|---|---|---|
| code | string | Points out the result of message processing. 1. OK - Processed successfully 2. REJECTED - An error has occurred while processing the request. |
| reasons (optional) |
object[string, string] | An object of the errors which occurred while processing the message. To be given with code=REJECTED only. |
| reasons.key | string | An error code. |
| reasons.ref (optional) |
string | A reference to the parameter where the error occurred. |
| messageId (optional) |
string | Message ID. To be given with code=OK only. |
| segmentsId (optional) |
array[string] | An array of identifiers for each message segment. Up to 255 elements inclusive. |
| description (optional) |
string | Error description. To be given with code=REJECTED only. |
Error codes¶
| Key | Ref | Description |
|---|---|---|
| billing.error | Payment is required | |
| forbidden | Sending is prohibited | |
| unknown | Unknown error | |
| invalid | messages[i].to | Wrong phone number is provided |
| invalid | messages[i].validity | Wrong lifetime is provided |
| invalid | messages[i].callbackUrl | Wrong URL is provided |
| length.too.long | messages[i].to | The maximum phone number length has been exceeded |
| length.too.long | messages[i].text | The maximum message text length has been exceeded |
| must.be.not.null | messages | The ‘messages’ array cannot be empty |
| invalid | messages[i].from | Wrong sender is provided |
| too.many.messages | messages | The maximum size of the ‘messages’ array has been exceeded |
Webhook¶
While creating the message status a POST request will be sent to the URL provided when sending the message in the callbackUrl parameter. 200 Ok is expected as the answer to the request.
In case the answer to the request is 500 Internal Error, there will be made 5 attempts to deliver the status with 1 minute interval.
Request example¶
{
"messageId": "string",
"status": "string",
"ts": 0,
"errorCode": 0
}
Request parameters¶
| Parameter | Data type | Status | Description |
|---|---|---|---|
| messageId | long | any | A unique message ID on the platform |
| ts | int | any | Points out the time for creating the ‘status’ object |
| status | enum | any | Delivery status code for the Viber message For more information see Possible statuses |
| errorCode (optional) |
int | rejected undeliverable |
A code for the reason for non-delivery of the message |
Possible statuses¶
| Parameter | Description |
|---|---|
| ACCEPTED | The message has been accepted. |
| SCHEDULED | The message has been scheduled. |
| ENROUTE | The message is in the queue for sending. |
| SENT | The message has been sent to the operator network. |
| DELIVERED | The message has been delivered to the user. |
| EXPIRED | The lifetime of the message has expired. |
| CLICKED | The recipient has followed the link in the message. |
| UNDELIVERABLE | Unable to deliver the message. |
| REJECTED | The message has been rejected by the operator or Devino. |
| UNKNOWN | An unknown error has occurred. |
Getting statuses¶
In addition to Webhook, it is possible to request the status of messages using POST /sms-stat/statuses/get-by-ids, passing an array of message identifiers in the request body with the authorization data in the header.
Request example¶
curl -X POST \
-H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
-H 'Content-Type: application/json' \
-d '[ "3482512350952730368" ]' \
https://api.devino.online/sms-stat/statuses/get-by-ids
Response example¶
{
"result": [
{
"smsId": 3482512350952730368,
"status": "DELIVERED",
"statusDateTime": "2020-11-11 11:20:35"
}
]
}
Possible statuses¶
| Parameter | Description |
|---|---|
| ACCEPTED | The message has been accepted. |
| SCHEDULED | The message has been scheduled. |
| ENROUTE | The message is in the queue for sending. |
| SENT | The message has been sent to the operator network. |
| DELIVERED | The message has been delivered to the user. |
| EXPIRED | The lifetime of the message has expired. |
| CLICKED | The recipient has followed the link in the message. |
| UNDELIVERABLE | Unable to deliver the message. |
| REJECTED | The message has been rejected by the operator or Devino. |
| UNKNOWN | An unknown error has occurred. |
Incoming webhook¶
How to connect
To receive incoming VIBER messages over HTTP, you must contact the company manager or contact technical support (support@devinotele.com).
To receive incoming SMS over SMPP, you need to have connection.
Example¶
{
"incomingMessageId": "3777714415805253122",
"to": "MyCompany",
"from": "79101111111",
"text": "Incoming message",
"transactionId": "a7d76677f699",
"countryName": "ru",
"operator": "",
"prefix": "2135",
"ts": "1587721283000"
}
Parameters¶
| Parameter | Data type | Description |
|---|---|---|
| incomingMessageId | long | Message ID |
| to | string | Address of the recipient |
| from | string | Sender address |
| text | string | Message text |
| transactionId | string | Operator incoming message ID |
| countryName | string | Country |
| operator | string | Operator |
| prefix | string | Prefix |
| ts | long | Points out the time for creating message with milliseconds |