Developer Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Send SMS

This endpoint allows you to send an SMS message to a recipient. A SMS message must have at least three components for it to properly be delivered to another person on the telephone network.

  • It must be from a valid phone number on your account.
  • It must be sent to a valid recipient’s phone number.
  • It must contain at a minimum, a short message.

How We Determine the From Number on an Outgoing SMS

  1. If you specify a user_id or pin value of a user on your account, we will attempt to use that user’s associated phone number if they have communication abilities enabled. This essentially means we’re sending a SMS out on behalf of this user.
  2. If you specify the from_number directly, we will attempt to use that as long as it matches a valid and active line on your account.
  3. If no from_number is specified, or no user_id/pin is specified, or the specified user has no number AND no caller id, we will attempt to use the account-wide text from number setting.
  4. If we cannot determine a from number, we return an error response to you.

How we Associate an Outgoing Text With a User

Texts sent using this endpoint can be associated with a user on your account. This means that we record the user’s id value with the call data record so that the text shows up in the user’s individual history, and in your reports. In order to associate the text with a user, you must specify the user_id or pin value below.

API Request

URL Parameters
Request Parameters
Parameter Type Usage Description
to_number string Required A phone number in 10 digit or E.164 format
payload integer Required The text message to send.
account_id integer Depends Specify the account id explicitly to send the SMS using this account. Optional for users. Required for integrators.
user_id integer Optional Associate the SMS with this user and attempt to use the user’s number as the SMS from number.
pin integer Optional Alternatively, specify the user with the PIN instead of user_id.
from_number integer Optional Specify the form number directly. This must be an active line on your account.
extra object Optional A JSON string containing any key:value pairs that you want to get sent back to you via the Push or RealTime API. See notes for extra data.
Response Body
   "success": true,
   "guid": "e3038b20-e487-497d-ab1e-361f4f8590a9",
      "sendType": "immediate",
      "uniqueId": "T.150472313191523499155290",
      "reason": "Nominal operation"
Error Code Description
OPT_OUT The recipient/to number is on the opt-out list
INVALID_ACCOUNT The account id, if specified, is not valid or you do not have access to it.
INVALID_CAMPAIGN The from number does not match an active, valid Line/Campaign on your account.
INVALID_FROM_NUMBER The from number is malformed or invalid.
INVALID_TO_NUMBER The recipient/to number is malformed or invalid.
INVALID_USER The specified user does not exist on the account.

A few notes on SMS message length

The SMS message specification only allows messages to be 160 characters long when using the GSM character set, and even shorter when using the UCS-2 character set, which has a 70 character limit. If you ask us to deliver a SMS message to a recipient that exceeds the character length, we will automatically split the message into multiple fragments, and deliver each one to the recipient. The recipient will then reconstruct the complete message, in order, from each fragment. This is called SMS concatenation, and is widely supported by all modern devices and software.

Note that you will be charged for each message we deliver to the recipient. If we break up your message into 5 individual SMS message fragments, we will record 5 outgoing messages against your account usage.

The same happens for incoming messages: If somebody sends you a SMS message that is composed of 5 message fragments, we will receive each one and combine them together into a single message for you. However, we will record 5 incoming SMS messages againt your account usage.