Receive Text Messages 

With the TextMagic API, you can establish a full two-way communication pipeline for sending and receiving text messages within your application.

Incoming messages callback

A callback is a mechanism that posts the JSON body of a received message to the URL on a server that you specify. The server application which receives the callback can save the message data into a database, send user notifications, etc.

Here is how to set up the incoming messages callback URL:

  1. Log in to TextMagic (or start a free trial if you haven’t registered yet).
  2. Go to the API page.
  3. Enter your callback URL into the Callback URL for incoming messages field.
  4. Click the Test button to test your URL.
  5. If it’s successful, click Save changes.

Your server should reply with a 200 OK response at this URL. If it does not, your callback URL will be treated as invalid and the inbound messages will not be passed to your application.

Call parameters

Your callback URL will be triggered immediately after a message reaches the TextMagic server. The parameters are passed by the POST method and contain the following information (i.e. exact copy of the reply resource). The Resource format is basically the format of the reply when making the request to the specific API resource.

Parameter
Example
Description
id 1782832 Inbound message ID.
sender 447860021130 Sender phone number.
receiver 447624800500 Receiver phone number (i.e. your dedicated or shared reply number).
messageTime 2012-11-28T18:38:28+0000 The time when the message reached the TextMagic server.
text Test reply Inbound message text.

REST inbound messages management

You can also interact with the inbound messages (or to put it simply, the replies) just like with other REST resources, such as with the templates, messages, contacts, and so on.

Get all inbound messages

To get all the replies, use this URI:

GET /api/v2/replies

with these parameters:

Name
Required?
Example
Description
page No

3

Fetch the specified results page. The default is 1.

limit No 25 The number of results per page. The default is 10.

You will receive a standard paginated response:

Parameter
Example
Description
page 3 The current fetched page.
limit 25 The number of results per page.
pageCount 150 The total number of pages.
resources Array of reply resources See next section for reply resource format details.

Get a single inbound message

To get a single inbound message, use:

GET /api/v2/replies/{id}

where id is the unique numeric ID for the inbound message. This command has no parameters.

Response format:

Parameter
Example
Description
id 1782832 The ID of the inbound message.
sender 447860021130 The sender’s phone number.
receiver 447624800500 The receiver’s phone number (i.e. your dedicated or shared reply number).
messageTime 2012-11-28T18:38:28+0000 The time when the message reached the TextMagic API endpoint.
text Test reply The text from the received message.

Delete a single inbound message

To delete an inbound message, use the following command:

DELETE /api/v2/replies/{id}

where id is the unique numeric ID for the inbound message. This command takes no parameters. If successful, it will return the standard HTTP status code for a DELETE response (204 No Content). Otherwise, you’ll receive an HTTP error code and an error message.

Note, deleted inbound message will disappear from TextMagic Online, chats, and any other place they are referenced.  So, be careful!

The next step

Congratulations! You can now use TextMagic API to receive SMS online messages and to manage replies. TextMagic API also allows you to Schedule recurring messages and manage SMS chats.