Receive an RCS MO

OpenMarket's RCS messaging supports Mobile Originated messages (MOs). MOs provide information back to you about the actions your end users take when they receive an RCS message. This might be information indicating that the end user clicked a link to your website. Additionally, MOs can also include the Auto-response feature, which provides automatic replies back to your users based on free-text the end user returns to you. If your account is provisioned for RCS MOs, and you've provided an endpoint, OpenMarket can return either of the following MO types based on the way an end user responds to an RCS message:

  • content - Also known as a free text response, this MO is returned when an end user replies with a free text response to an RCS message. The MO will contain the text response. For example, if a user responds with STOP, an MO is returned that includes the STOP response. For this type of MO, the first word in the MO is matched against a list of keywords. If there is a match, the MO is forwarded on to the endpoint. If no keyword is found, the default behavior is to log the MO message and then drop it. However, your account can be provisioned to receive all MOs, even if those MOs contain unrecognized keywords. For more information on how keywords are used, see Using auto-response for a free text keyword reply.
  • postback - Returned when an end user clicks an action button sent in an RCS message. The MO will contain the action the end user performed. For an example, if an end user clicks an action to dial a phone number, that action is returned in the MO. This MO uses the customerData parameter to process the MO. If the customerData returned in the MO is matched against the same provisioned customerData, then the MO is forwarded on to the endpoint. If there is no matching customerData found, the default behavior is to log the MO message then drop it. However, your account can be provisioned to receive all MOs, even if those MOs contain unrecognized customerData. For more information using the customerData parameter see Using the customerData parameter for actions or suggestions.

For a description of MO parameters and examples, see RCS MO Parameters and Examples.

Authorization on the endpoint

Authorization on the endpoint is separate from authorization when using the Invoke API to send the RCS message. If you want to set authorization on the endpoint, you need to provide basic authorization credentials.

Using auto-response for a keyword reply

The auto-response feature lets your system automatically send a message in response to keyword sent by an end user. For example, let's say you send an RCS message and an end user texts SUPPORT in response. OpenMarket's system compares the keyword, support, against a preconfigured list of words that's associated with a specific auto-response message. The list of words for this example could include support, aid, help, and assistance.

When our system matches a keyword to a list, we can automatically send the response message associated with the list.

Note: Only the first word of an end user's response is matched. Partial word matching is not supported. For example, if a user sends back a response saying "Please stop sending me messages", keyword matching will fail as the word "Please" is compared against the preconfigured list of words.

Setting up auto-response

To use auto-response:

  • Make sure your OpenMarket account is provisioned to receive MOs.
  • Provide OpenMarket with the list of keywords that will trigger a particular auto-response. Note that keywords are case-insensitive and need to be unique per auto-response.

We can configure auto-response to work in one of three ways:

  • We send the auto-response message on your behalf.
  • We send the auto-response message to your system and you forward it to the end user.
  • We send the auto-response message on your behalf and also send you a notification that we sent it.

OpenMarket can configure auto-response for free text MOs without forwarding this information back to you.

Unrecognized keywords

OpenMarket can provision an unrecognized keyword flow that auto-responds to an end user's text if we cannot recognize any keywords in the message. For example, say an end user sends random characters or a word that's not in a keyword list. Because we look only at the first word of the end user's response, if the user sends a complete sentence, such as "How do I contact Support?" OpenMarket will look only at the word "How". On not recognizing that word, an auto-response message is returned indicating that the user's message was not recognized. The auto-response message can then be set up so that an end user must respond with one of a selection of options. For example, an auto-response message might be "Sorry, we did not recognize that. Please text back either A, B, or C."

Note: If requested, OpenMarket can manage a blacklist of users on your behalf but can only provision this for text responses (where OpenMarket does the keyword matching). If you require blacklist capability for Chip List replies/actions, then it is your responsibility to manage the list and to set the customerData parameter to contain any information you might need.

Auto-response and multiple languages

Auto-response can be set up to use multiple languages, allowing your end users to interact with you in the language of their choice. The following two examples show how you can use multiple languages in an auto-response.

  1. Set up separate keywords for different languages so that a response is always in the language that your end user sends a message. For example, if your end user sends "HELP" in English, then a response is sent in English; however, if your end user sends "AYUDA" in Spanish, then the response back to the end user can be in Spanish.

  2. Set up a keyword and list of aliases together, regardless of the language, then configure the required auto-response text by country. When a message is received from an end user, OpenMarket can determine the country code from the end user's phone number and respond with the configured text for that country. This allows you to respond differently based on the end user's country. For example your response to "HELP" may include a phone number, which will vary depending on whether the user is in the US, the UK or Australia, etc.

Using the customerData parameter for actions and suggestions

An Invoke API request uses an optional customerData parameter to return information back to you about an end user. When an end user taps a suggested reply or action, the customerData parameter associated with that reply or action will be included in the MO sent to you with details about the end user.

This feature can only be enabled if

  • an account is provisioned for MOs.
  • an endpoint is provided to which MOs are sent.

The customerData parameter is set within a reply or action suggestion of an invoke request. See reply or action in Invoke API Parameters. The parameter can be passed in multiple replies and/or actions within an RCS message; however, the parameter should be unique for each instance.

If an account is neither provisioned for MOs, nor an endpoint is provided, Chip Lists are still supported in RCS messages, but no MOs are returned. If a customer's account is provisioned for MOs and an endpoint provided, but the customerData parameter is not passed in a request, MOs can still be returned. However, the MO data is not associated with any particular reply or action since the parameter was not passed, making it more difficult to extrapolate data. For that reason, if MOs are required, we advise passing the parameter in the request.