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.

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 /sms/messages \
 -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
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.
undeliverable	Unable to deliver the message.
rejected	The message has been rejected by the operator or Devino.
deleted	The message has been deleted from the queue for sending.
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 /sms-stat/statuses/get-by-ids \
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
 -H 'Content-Type: application/json' \
 -d '[ "3482512350952730368" ]' \
https://api.devino.online/sms/messages

Response example

{
  "result": [
    {
      "smsId": 3482512350952730368,
      "status": "DELIVERED",
      "statusDateTime": "2020-11-11 11:20:35"
    }
  ]
}

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