.. _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" }