Making Inject Message Requests

The Inject Message operation enables you to send messages into MEP, via an HTTP request, as if they were sent from an end user. Read this page to find out how to use the inject message operation, try out the operations using cURL, and see the results in the MEP UI.

When you inject a message using this operation, MEP then processes the message as if it had been sent directly from the end user rather than from your platform. This enables you to use an external platform, such as a web service, to trigger a MEP service for an end user. Variables related to the end user or service can also be set in the same request.

One common use of this interface is sending mobile numbers to MEP that end users have submitted through a web form, triggering a double opt-in service that responds to the end user via SMS. As well as sending an automatic SMS response message to the end user, MEP could also add the end user to a subscription list and verify the mobile number’s existence.

Note: The Invoke Service operation supports the same basic functionality as the Inject Message operation. The primary differences between the two are that Invoke Service provides enhanced security and high availability capabilities. If you are an existing customer using the Inject Message operation, contact your OpenMarket account manager to determine the migration effort. If you are a new customer, you may want to contact your account manager to determine which operation best fits your needs.

Before we begin

Before beginning, you'll need a MEP account provisioned, and you'll need to ask your OpenMarket account manager to also:

  • Activate the interface for your account
  • Provide you with an inject routing code (or codes) designed to receive these requests

Once provisioned, log into MEP and make sure in the MEP user account that you have the following settings:

  • Main Roles
    • Routing Manager, or Routing User, or Routing Viewer
  • Other Roles
    • HTTP Inject API user
  • Routing - Short Codes
    • The inject routing code selected (users with the Routing Manager permission will automatically have access to the code)

Retrieve the inject routing code

You can find your inject routing codes on the Routing home page. These are normally text codes like "ACME_HTTP_inject". Use the code as it is exactly as written under "Name".

Screenshot of the Routing home page, showing an inject routing code

Inject a message

(Operation: Inject a Message)

This example request injects a message from a fictional US phone number into your service. In cURL call, you'll need to change the:

  • username and password to your own details
  • example inject routing code ACME_HTTP_inject to your own code
  • example subscription collection ID 1A2B3C4D5E to the ID of your own collection
curl -D - -X GET "https://cmx2api.openmarket.com/InjectMessage?code=ACME_HTTP_inject&username=MyUsername&password=P4S5W0Rd&from=12515550130&msg=hello&encoding=UTF-8"

If your request is successful, OpenMarket will return a synchronous response, similar to the following.

HTTP/1.1 200 OK
Date: Tue, 15 Mar 2016 16:36:54 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
Content-Type: text/plain
			
2A019B0EB7DB0DF

The hexadecimal code in the request body (e.g. 2A019B0EB7DB0DF) is a unique identifier for the message in OpenMarket's systems.

If desired, you could have the routing code attached to a service, and replace the mobile number and message sent, and begin testing the routing to the service and the flow of the service. However, to test that the operation is working successfully, all you need is an active inject routing code.

See the results

To confirm that your routing code received the message:

  1. Navigate to the Routing home page.

  2. Click on the envelope icon for the inject routing code.

    Screenshot highlighting the envelope icon for an inject routing code

    This takes you to the Filter Message History screen for the routing code. This will show that a message was sent from the number (12515550130) to the code.

    Screenshot of the filter message history page, showing a message sent into the routing code

Including variables in the request

When you inject a message into MEP, you can set variables related to both the session and the end user. This enables you to create or update custom variables with each injected message.

This feature acts much the same as if you are creating or updating a variable at the beginning of the service using a service handler. The variables are set before the message is routed and are accessible immediately within the triggered service.

You can send an expression as part of the variable's value, as long as the expression doesn't require an initial value that hasn't been defined (for example, you can't set a self-referential expression). As per normal with variables, you can only update custom variables and not built-in variables.

You can specify variables with the following scope:

  • request and session
  • user, userservice, and userservicecoll

For information about variables and expressions, see Overview.