Send Message

Overview

This web service can be used to send an outgoing message via web service implemented by Service Provider. Text messages of arbitrary length are supported.

Note

This web service handles outgoing messages only. To implement both sending and receiving of text messages via web services, you will also need to implement Fetch Messages web service, plus a few others if you would like to utilize push notifications about incoming messages.

Parameters

Parameter templates for Send Message web service can use any variables from Global parameters and Account parameters scopes. There are also additional, service-specific parameters for this service:

sms_to

This parameter will be replaced with the address of desired recipient. It will be a phone number or SIP address where the message is to be delivered. The exact format of this address can be tweaked using Number Rewriting. See Account XML for more details.

Note

Acrobits apps support sending messages to multiple recipients. In this case, the web service will be called for every recipient separately.

sms_body

The body of the message to be sent. The string will be encoded in UTF-8.

smart

In case Smart Contacts are enabled, this flag will be set to 1 in case sms_to is recognized as “smart” number.

Configuration

The following Account XML keys are relevant for Send Message web service configuration:

genericSmsSendUrl

Contains the URL, including URL scheme, of the web service, possibly also with query string.

https://example.com/send_message/?from=%account[username]%&password=%account[password]%&to=%sms_to%&body=%sms_body%

genericSmsPostData

If filled in, the app will use POST request to send the message.

Example ( for application/x-www-form-urlencoded):

from=%account[username]%&password=%account[password]%&to=%sms_to%&body=%sms_body%

Example ( for application/json ):

{ "from" : "%account[username]%", "password" : "%account[password]%", "to" : "%sms_to%", "body" : "%sms_body%" }

genericSmsContentType

Specifies the value of Content-Type header to be sent in the request. If not specified, the app will default to application/x-www-form-urlencoded

Response

The response will be considered successful if the HTTP response code is 2xx.

In case of non-2xx response, the app will check for a “message” field in response body. If present, it will show this string as error message to the user, otherwise the app takes first 100 characters of the raw response body and shows that to the user instead.

Examples

GET method, XML

request:

GET /send_message/?from=johndow&password=12345678&sms_to=%2B15551231234&sms_body=Hello%20World HTTP/1.1
Host: example.com
Connection: close
Cache-Control: max-age=0
User-Agent: CloudSoftphone/1.5.6

success response:

HTTP/1.1 200 OK
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Length: 0
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive

error response:

HTTP/1.1 402 Payment Required
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Length: 123
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: text/xml

<response><message>Not enough credit</message></response>

POST method, JSON

request:

POST /send_message/ HTTP/1.1
Host: example.com
Connection: close
Cache-Control: max-age=0
User-Agent: CloudSoftphone/1.5.6
Content-Type: application/json
Content-Length: 183


{
    "from"        : "johndow",
    "password"    : "12345678",
    "sms_to"      : "+1(555)123-1234",
    "sms_body"    : "Hello World"
}

success response:

HTTP/1.1 200 OK
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Length: 0
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive

error response:

HTTP/1.1 406 Not Acceptable
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Type: application/json
Content-Length: 123
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive

{
    "message"        : "Invalid recipient"
}