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 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.

int validity:

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)

Date schedule:

(optional) date to schedule the message to be sent at a given time (Europe/London time)

Returns:


an Hashtable with 4 keys: 'message_id', 'scheduled_id', 'credits_used', 'status' e.g.
result.get("message_id")

Hashtable key

Value

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_id 

String. 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:

Code

Meaning

0Refused (bad number or trying international sending without a valid account).
1Bad username or password.
2You have zero credits.
3The originator is invalid or too long.
4

The originator is invalid or missing.

5The message is invalid or too long.
6You have insufficient credits to send this message.
7

The message is invalid or missing.

8

The message contains unsupported characters (these will be listed in the error message).

9

The mobile number is invalid or too short.

10The mobile number is invalid or not an integer.
30Invalid 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.

33

If 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.