Skip to end of metadata
Go to start of metadata

 

Send a text message to the specified recipient. Optionally, sends can be scheduled.
See also What is a sent message?

With the minimum arguments required, sends 'my message' to 447000000000 with sender ID 'Sender':

Example

As above, but sets validity to 72 hours and is scheduled for sending on 1st Jan 2013 at 01:00 GMT:

Example

Arguments:

 

string $message: 

the textual content of the message to be sent. Up to 612 characters from the GSM alphabet. See Supported Characters below for the characters we support. Please ensure messages are encoded in UTF-8.

string $mobile_number: 

the mobile number of the intended recipient, in international format, e.g. 447000000000. Only one number is allowed. To send a message to multiple recipients, you must call the function for each number.

string $originator:

sender ID: text (up to 11 alpha-numeric characters) or the international mobile number (up to 16 digits) of the sender, to be displayed to the recipient, e.g. 447777123123 for a UK number.

integer $validity: 

(optional) an integer from 1 to 72 (the default), indicating the number of hours during which the message is valid for delivery.
Messages which cannot be delivered within the specified time will fail.

string $email:

(optional) available to txtUs Plus customers only. Specifies the email address for incoming responses. If you specify an email address, you must specify an originator that is a txtUs Plus number that is on your account, or you will get an error response.

string $custom:

(optional) an alpha-numeric string, 1-20 characters long, which will be used to 'tag' your outgoing message and will appear in delivery reports, thus facilitating filtering of reports (see getDeliveryReport function)

string $schedule:

(optional) date to schedule the message to be sent at a given time (Europe/London time), should be in ISO 8601 format or a Unix timestamp

Supported Characters:

When constructing the message to be sent you should be aware that not all characters are supported by the GSM networks. They have a specific character set that they use. It shouldn’t be of concern to 99% of people since the English alphabet is supported, plus some common accented characters.
Please note we expect the data to be encoded in UTF-8. You will need to convert your message first if you are using a different character set, for example people sometimes store message templates in databases in one of the latin character sets. If you are storing messages in a database you may need to check the basic character set.

Returns:

an array with 4 keys: 'message_id', 'scheduled_id', 'credits_used', 'status' e.g. $result['message_id']

Array keyValue
message_id 

Integer. The unique ID of the message sent. You can use this ID to find the status of the sent message in a delivery report. However for scheduled messages (i.e. where you have specified a 'schedule' argument), the ID will be zero.

 scheduled_idString. The unique ID of the scheduled message. You can use this ID later to delete a previously scheduled message. Unless the message has been scheduled for a future date, the ID will be zero.
 credits_used Integer. The number of credits used to send the message (up to 3 for UK or 6 for international). If the message is scheduled for future sending, this value indicates how many credits will be used when it is sent.
 status String. Values possible are SENT, QUEUED, or SCHEDULED. Indicates whether the message was put in a queue for processing as soon as resources allow (QUEUED), sent immediately (SENT), or scheduled for future sending at your request (SCHEDULED).

Specific error codes:

CodeMeaning
0Refused (bad number or trying international sending without a valid account).
1Bad username or password.
2

You have zero credits.

3The originator is invalid or too long.
4The originator is invalid or missing.
5The message is invalid or too long.
6You have insufficient credits to send this message.
7The message is invalid or missing.
8The message contains unsupported characters (these will be listed in the error message).
9The mobile number is invalid or too short.
10The mobile number is invalid or not an integer.
30

Invalid email address format.

31

An email address was specified, but the originator specified was not a txtUs number on your account.

32

If specified, the validity period (in hours) must be between 1 and 72 inclusive.

33If specified, the custom field must be alpha-numeric and up to 20 characters in length.
34The 'schedule' parameter is not in ISO 8601 date format.

 

 

 

 

You must know!

Our example code is an illustration of how you might integrate with our systems and is not certified for production environments. You are responsible for testing and QA.