Receive and Reply to Messages
This tutorial will explain the steps involved to receive message responses and to reply to them with the API
Last updated
Was this helpful?
Jump to...Create Free API Account
This tutorial will explain the steps involved to receive message responses and to reply to them with the API
Last updated
Was this helpful?
See below for details of each step of the process to ensure you have the data required to complete this process.
An initial message is sent, just as other messages, with a request to the /send endpoint of the API. But in order to track this message for potential future replies, this request must contain identifying metadata.
This identifier can be set in either of the following parameters when creating your initial request: externalId or tags .
Either parameter can be used to ensure that the message-reply payload sent your endpoint will contain the necessary data needed for you to create a reply.
externalId parameterThe externalId parameter is an optional string field intended for you create and assign your own identifier for each message request. This is strongly recommended as it ensures consistency between your system and Mobile Text Alerts. With an externalId MTA can return this specific identifier in all future webhook calls related to this message.
Example: "externalId": "RequestId-4e0242e2-d101"
tags parameterYou can also use the tags parameter, a general purpose tagging system, as a way to assign any additional data in the request to the /send endpoint. The tags object is tracked with the outbound message record and will be reflected in all webhook calls related to this outbound message. The tags can contain metadata about the recipient, the message send request, an identifier to you external system and any other data for your use case.
Example: "tags": {"ABCompanyId": "4e0242e2-d101"}
A successful /send request will return a messageId as part of the response. This is the unique identifier of the request assigned by Mobile Text Alerts. It is recommended to store this messageId in your system to reconcile with your provided internal identifier.
fromNumber - identifies the phone number of the subscriber that sent the reply
externalId - the original string you provided on the initial outbound message
messageId - the internal MTA identifier for this inbound message reply
message - (SMS/text only replies) the full contents of the subscriber's reply.
url - (MMS replies) a URL where the inbound media has been re-hosted. If you plan to use this supplied media within your application, it is recommended that you download and cache this resource for further use.
tags - the original tag metadata you provided on the initial outbound message
The fromNumber identifies the phone number of the subscriber that replied, but that subscriber may receive messages from different numbers on your account or may be replying to different messages at different points in time. To avoid this confusion, instead of associating your reply to a subscriber, it is best to associate a reply to an outbound message.
You can determine the initial outbound message being replied to by retrieving the original outbound message from your system, using the externalId and/or tags in the reply payload. This enables your application to produce a consistently ordered chain of messages, both outbound and inbound, needed to support 2-way conversations.
To form your response message request, you can reuse the initial outbound number by setting the same longcodeId value in the /send request that was previously used for the original outbound message. Set the recipient to the value of the fromNumber. Ensure that you provide a new internal identifier for this outbound message in order to repeat this process of send and reply.
Message reply notifications, will be sent via webhook calls. A message-reply event sent to your webhook URL will contains the following field data in the payload that is relevant to sending response messages:
Refer to the for additional field information.