.. _send_message_webservice:
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 :ref:`fetch_messages_webservice` 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 :ref:`global-params` and :ref:`account-params`
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 :ref:`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.
content_type
~~~~~~~~~~~~
Set to ``text/plain`` (optional) for text messages,
``application/x-acro-filetransfer+json`` (required) for media messages and ``application/x-acro-disposition-notification``
(required) for disposition notifications. The server should store the content type along with
the message body and in case :ref:`fetch_messages_webservice` web service is also implemented, it should send this
content type in the response for every message.
disposition_notification
~~~~~~~~~~~~~~~~~~~~~~~~
Information whether the delivery/display notifications are requested by the user and the IMDN-related identifier.
The server should store the disposition notification along with the message body and the content type and
in case :ref:`fetch_messages_webservice` web service is also implemented, it should send this
disposition notification in the response for every message.
Configuration
-------------
The following :ref:`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.
.. code-block:: none
https://example.com/send_message/?from=%account[username]%&password=%account[password]%&to=%sms_to%&body=%sms_body%
``genericSmsSendPostData``
~~~~~~~~~~~~~~~~~~~~~~
If filled in, the app will use POST request to send the message.
Example ( for application/x-www-form-urlencoded):
.. code-block:: none
from=%account[username]%&password=%account[password]%&to=%sms_to%&body=%sms_body%
Example ( for application/json ):
.. code-block:: json
{ "from" : "%account[username]%", "password" : "%account[password]%", "to" : "%sms_to%", "body" : "%sms_body%" }
.. note::
The old **genericSmsPostData** field has been ``DEPRECATED`` and is not guaranteed to work.
The **genericSmsSendPostData** field must be now filled in to use POST for sending messages.
``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.
In case of 2xx response, the body may contain an optional ``sms_id`` field, which contains the identifier of the
sent message assigned by server. This identifier is stored on the client and is used to detect duplicates in
:ref:`fetch_messages_webservice` in case sent messages are to be synchronized as well.
Examples
--------
GET method, XML
~~~~~~~~~~~~~~~
request:
.. code-block:: http
GET /send_message/?from=johndow&password=12345678&sms_to=%2B15551231234&sms_body=Hello%20World&content_type=text/plain&disposition_notification=xkXRBMCL.twvNcfC9:positive-delivery,display HTTP/1.1
Host: example.com
Connection: close
Cache-Control: max-age=0
User-Agent: CloudSoftphone/1.5.6
success response:
.. code-block:: http
HTTP/1.1 200 OK
Date: Sun, 15 Mar 2025 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Length: 54
Keep-Alive: timeout=5, max=100
Content-Type: text/xml
Connection: Keep-Alive
afe3259dc234
error response:
.. code-block:: http
HTTP/1.1 402 Payment Required
Date: Sun, 15 Mar 2025 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
Not enough credit
POST method, JSON
~~~~~~~~~~~~~~~~~
request:
.. code-block:: http
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",
"content_type" : "text/plain",
"disposition_notification" : "xkXRBMCL.twvNcfC9:positive-delivery, display"
}
success response:
.. code-block:: http
HTTP/1.1 200 OK
Date: Sun, 15 Mar 2025 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Length: 23
Content-Type: application/json
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
{
"sms_id" : "12456"
}
error response:
.. code-block:: http
HTTP/1.1 406 Not Acceptable
Date: Sun, 15 Mar 2025 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"
}