Docs

Send message

/accounts/{accountSID}/messages

Overview

This request sends an SMS message to a phone number. Only phone numbers rented from Apico can be used as senders’ numbers.

With this request, you can provide a controller URL where Apico will make its own requests every time a message status changes. This allows you to be informed on the current message status, and also send XML instructions in response. 

Input parameters

Parameter

Required?

Description

Default value

from

yes

A phone number to be used as a message sender. This number must be acquired from Apico.

N/A

to

yes

Recipient’s phone number.

Phone numbers should be formatted with a country code.

For example, 35315313424.

N/A

text

yes

Text of the message.

Max 160 Latin characters or 70 Unicode characters.

N/A

controller

no

URL to be used to make a request for an XML controller file.

The current message status will be transmitted along with the other request parameters.

In case Apico API receives an XML file in response, it starts processing commands. If no XML file is provided in response, Apico does nothing and keeps requesting to controller URL in the moments the message status changes.

N/A

method

no

Method to be used to make a request.

POST

Request example

The following cURL example demonstrates sending a message.

curl –X POST ‘https://api.apico.net/v2/accounts/{accountSID}/messages’ \
-H ‘Content-Type: application/json’ \
-d ‘{ \
     “from”: ”35315313424”, \
     “to”: ”447860041755”, \
     “text”: “Apico API provides a really cool SMS messaging service” \
    }’ \
-u {accountSID}:{authToken}

Response example

{
    "status_code": 201,
    "status_message": "CREATED",
    "uri": "/accounts/{accountSID}/messages/{messageSID}"
}

Apico request parameters being sent to controller URL

The following parameters are sent to controller URL if it is provided in the request. XML controller file describing processing rules expected in return. For more information, refer to ApicoXML.

Parameter name

Description

message_sid

Message unique identifier.

account_sid

Account unique identifier.

from

Sender’s phone number.

to

Recipient’s phone number.

text

Message text.

status

The current message status.

For more information on possible statuses, see below.

status_message

Error details.

It is sent only if the status value is failed.

Apico request example

{
    "message_sid": "{messageSID}",
    "account_sid": "{accountSID}",
    "from": "35315313424",
    "to": "447860041755",
    "text": "Apico API provides a really cool SMS messaging service",
    "status": "queued"
}

Possible message statuses

 

Status value

Description

queued

Message is going to be sent.

sent

Message was sent.

received

Message was received by your Apico number.

Works only for inbound messages.

delivered

Message was delivered to the recipient.

failed

Message was not delivered to the recipient.

If this happens, an error message is included in Apico request.