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:
- Log in to Textmagic (or start a free trial if you haven’t registered yet).
- Go to the API page.
- Enter your callback URL into the Callback URL for incoming messages field.
- Click the Test button to test your URL.
- 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 |
|
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.
