Transferring calls
Open Recipe


This endpoint is the primary destination for sending messages via 23shout's API.

It allows you to send messages, monitor their sending state, and specify how it's handled in 23shout for the team. Many of the edge cases and precedences are described in the Body Params below, so this article will mostly discuss restrictions and further applications of the endpoint.

Sending with Word Names

23shout supports sending messages from alphanumeric strings, e.g. your initial authentication SMS from 23shout came from 23SHOUT instead of a phone number.

Word Names can be up to 11 characters long, and support alphanumeric characters including the space.

Not all countries support Word Names however (notably New Zealand), if a country is unable to receive a Word Name 23shout will fallback to a US number controlled by us and shared amongst teams.

For this reason it's advisable to check if the receiving country supports such a format before sending the SMS to avoid your message being grouped with other 23shout customers.

Support for falling back to another of your numbers is a feature currently in progress by our development team and should arrive soon.


Restricted Word Names

By default 23shout restricts you from sending certain Word Names to do our part in the fight against spam.

These include 23SHOUT, ADMIN, various bank names, and more. If you hit a restricted Word Name you will be returned a 23#ApiError object.

Status callbacks

23shout uses REST hooks to get you data based on your message. If you specify a URL a request will be sent each time your message changes status with a body containing the Message, and an ID of the subscription you created.

The request will be a POST request, your endpoint must be of the https:// scheme, and the body will be in JSON format.

Currently we support the following events to return...

draftYour message has been created, but not yet sent per your request.
sendingThe messaging is currently being sent.
sentThe message has successfully been sent without error.
deliveredWe've received delivery confirmation that the device has in fact received the message.
readThe message has been read by the destination device. Not supported on SMS messages.
failedThe messaged failed to send, the request will also specify why. This can be an error in your request, or an upstream issue with our provider.

For an example of a response, visit the REST hooks section.

Click Try It! to start a request and see the response here!