Making Broadcast Requests

The broadcast operations provide a programmatic way to create SMS, MMS, and service broadcasts. Read this page to find out how to use broadcast operations, retrieve any IDs you need, and to try out the operations using cURL.

Before we begin

Before beginning, you'll need a MEP account provisioned. Once provisioned, log into MEP and make sure in the MEP user account that you have the following settings:

  • In Main Roles:
    • Broadcasts: User (ensure that the "user" button is selected)

Underneath the Main Roles check that the user has access to the correct options and accounts:

  • Broadcasts — Broadcast Types

  • System — Accounts

    If the user will be broadcasting SMS or MMS messages, then they will require access to the SMS- or MMS-specific Gateway Account.

Users with the system manager permission will automatically have full access to the different broadcast types and gateway accounts.

Screenshot of the account settings required to use broadcast operations

Retrieve a subscription ID

Broadcast requests must include an ID for a subscription. These are the broadcast recipients. You can include multiple subscription IDs in the request.

For testing purposes, create a subscription that contains either no mobile numbers, or only your test mobile phone numbers.

To retrieve a subscription ID using MEP:

  1. Click the Subscriptions tab.
  2. Click on the subscription for which you want the ID. This opens the subscription's properties page.

  3. Find the ID in the first section (Subscription Details) of the page.

    Image of subscription properties page with an ID highlighted

You can also retrieve a subscription ID programmatically using the Get Subscriptions operation.

Retrieve your SMS or MMS Gateway Account ID

To broadcast SMS or MMS messages, you will need your SMS or MMS Gateway Account API ID. This is available within the MEP UI. To access the ID:

  1. Click the System tab.

  2. Click Gateway Accounts.

    A list of your gateway accounts appears.

    Gateway accounts home page

  3. Click the (View Account Details) icon for the gateway account.

    A pop-up appears with the details for the gateway account including the Account API ID.

    Gateway accounts page with modal open

Note: These account API IDs are MEP specific, and are not the same as your account ID for any other OpenMarket service or product.

Send an SMS broadcast

(Operation: Submit an SMS Broadcast)

Now you can send your first SMS broadcast. In the cURL call, you'll need to change:

  • username and password to your own details
  • example subscription ID A1B2C3D4E5F6 to the ID of your own subscription
  • example account ID F9E8D7C6B5A4 to your own SMS Gateway Account API ID
curl -D - -X GET "https://cmx2api.openmarket.com/broadcastapi/v1/createsmsbroadcast?username=MyUsername&password=P4S5W0Rd&subscriptions=A1B2C3D4E5F6&account=F9E8D7C6B5A4&name=MEP+is+Great&message=Thanks+for+messaging+with+MEP%21&charactersupport=gsm&multipart=false"

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
			
<?xml version="1.0" encoding="ISO-8859-1"?>
<broadcast>
   <id>7FCA39AF17563F67</id>
</broadcast>

This sends the broadcast SMS immediately. You can see the results of a broadcast both during and after a broadcast via the MEP UI. See Viewing and Understanding Broadcast Results.

Send an MMS broadcast

(Operation: Submit an MMS Broadcast)

To send a broadcast MMS, you will need the MMS content available as a ZIP file. To find out more about this see: Creating an MMS zip file for a broadcast MMS message.

To send the MMS broadcast change the following In the cURL call:

  • username and password to your own details
  • example subscription ID A1B2C3D4E5F6 to the ID of your own subscription
  • example account ID F9E8D7C6B5A4 to your own MMS Gateway Account API ID
  • example url http://example.com/happyday.zip to the location of your MMS message
curl -D - -X GET "https://cmx2api.openmarket.com/subscriptionapi/createmmsbroadcast?username=MyUsername&password=P4S5W0Rd&subscriptions=A1B2C3D4E5F6&account=F9E8D7C6B5A4&contents=http://example.com/happyday.zip&name=Happy+campaign&subject=Have+a+happy+day+on+us"

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
			
<?xml version="1.0" ?>
<broadcast>
   <id>AF3F6717567FCA39</id>
</broadcast>

This sends the broadcast SMS immediately. You can see the results of a broadcast both during and after a broadcast via the MEP UI. See Viewing and Understanding Broadcast Results.

Note: You can only broadcast MMS messages if you have an MMS-capable MEP account. Contact your OpenMarket account manager if you are interested in sending MMS messages.

Retrieve a service ID

To try out a service broadcast we will need the ID of a service that you want to trigger. If you're new to MEP, then create an auto-respond service; e.g. a service that sends a "Hello World" SMS back to the mobile number.

To find a service ID:

  1. Click the Services tab.

  2. Click to expand the Service Collection containing the service whose service ID you want to retrieve.

    The ID column shows the service ID of each service.

    Services home page with Service IDs indicated

Send a Service broadcast

(Operation: Submit a Service Broadcast)

Finally, let's send the service broadcast. In the cURL call, you'll need to change:

  • username and password to your own details
  • example subscription ID A1B2C3D4E5F6 to the ID of your own subscription
  • example service ID F9E8D7C6B5A4 to the ID of your own service
curl -D - -X GET "https://cmx2api.openmarket.com/subscriptionapi/createservicebroadcast?username=MyUsername&password=P4S5W0Rd&serviceid=F9E8D7C6B5A4&subscriptions=A1B2C3D4E5F6&name=Trigger+Thank+You+Service"

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
			
<?xml version="1.0" ?>
<broadcast>
   <id>17567FCA39AF3F67</id>
</broadcast>

This triggers the service broadcast immediately. You can see the results of a broadcast both during and after a broadcast via the MEP UI. See Viewing and Understanding Broadcast Results.