Receive and Reply to Messages

This tutorial will explain the steps involved to receive message responses and to reply to them with the API

Prerequisite:

In order to receive message reply notifications, you must first configure a message-reply webhook.

If you haven't yet configured any webhooks for your account see: Setting up your first webhook

Overview of process:

1. Send outbound message

2. User receives message and replies, you receive the reply

3. Create response to a reply

See below for details of each step of the process to ensure you have the data required to complete this process.

Step 1: Send outbound message

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.

Use request metadata to add an internal identifier

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.

- Include the externalId parameter

The 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"

- Include the tags parameter

You 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"}

Send the request

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.

Step 2: User receives message and replies, you receive the reply

Message reply notifications, will be sent via message-reply 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:

• 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

Refer to the message-reply webhook payload for additional field information.

Step 3: Create response to a reply

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.