Send a Branded Message

A branded message is a message that contains a company logo in addition to text. Technically speaking a branded message is an RCS message, but you make the request via the SMS API.

To send a branded message you'll include campaignId in the request. We provide this ID to you after we configure your account for the Branded Messaging service and your brand is registered as a bot.

When our SMS API sees campaignId in a message request, it passes the request to our RCS platform, which evaluates whether the message can be delivered as a branded message. Any end user whose device is RCS-compatible will receive the branded message. End users without RCS-compatible devices will receive a regular SMS message.

Quick facts

Method

POST with JSON

Returns

JSON

Available

US, UK, and countries where mobile network operators accept RCS messages

Prerequisites

Your OpenMarket account must be configured for SMS and Branded Messaging, and the request must include a campaign ID

More information

See Overview.

Make a request

Definition

POST https://smsc.openmarket.com/sms/v4/mt

There are no URL parameters for this endpoint.

This endpoint supports versions Transport Layer Security (TLS) 1.2 and 1.1.

Header fields

You must provide your authentication details using Basic authentication in the header.

Example header

POST /sms/v4/mt HTTP/1.1
Host: smsc.openmarket.com
Content-Type: application/json; charset=UTF-8 
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

Field

Description

Authorization

Your account ID and password, separated by a colon, and then base64 encoded. Your account ID and password are case-sensitive. For help with Basic authentication see Authenticate with OpenMarket.

Content-Type

Specify application/json for this request.

Request body

The request body contains details for sending the branded message.

The request differs from 'Send an SMS' mainly in that you'll include campaignId in the request instead of source object. We provide the value for campaignId after your brand is registered as a bot.

Note that if you send a request with both campaignId and a source object, the API will reject the message.

{
    "mobileTerminate": {
        "interaction": "two-way",
        "options": {
            "campaignId": "TestCampaign"
        },
        "destination": {
            "address": "12125550123"
        },
        "message": {
            "content": "This is a test smsRcs message!",
            "type": "text",
            "validityPeriod": 259200
        },
        "delivery": {
            "receiptRequested": "final",
            "url": "https:my.example.com/receiver.php"
        }
    }
}

JSON properties

The JSON body has a top-level object that contains one member, mobileTerminate.

Only one of this object is allowed.

mobileTerminate object

Member

Description

interaction

Indicates whether this is a global one-way or two-way message. You do not need to specify interaction if you are messaging in the US or Canada (the value is ignored). Options are:

  • one-way — Uses global one-way messaging
  • two-way — Uses global two-way messaging

The values are case-sensitive.

Required: no

Default: See Automated Originator Selection.

Type: string

promotional

Required for India messaging only. This identifies whether the message is transactional or promotional. For any non-India messaging, this field is ignored. See Sending to India for more information. Options are:

  • true — The message is promotional
  • false — The message is transactional

Required: no

Default: false

Type: Boolean

options object

Contains a variety of optional message sending options. The exception is campaignId for sending a branded message. This is required.

Member

Description

programId

We provide this ID to you for SMS messaging, and we combine it with the originator (source) you're using. You must include programId for SMS messages sent to US numbers.

Since some branded messages are delivered via SMS as text messages, you will need to include programId in requests for US messages.

Required: no for global messaging, yes for messages sent via short code in the US 

Default: no default

Type: string, 1-50 characters, not case-sensitive

campaignId

Required for a branded message request. OpenMarket provides you with the value, which is between 1-50 characters.

NOTE: Do not include both campaignId and source object. If you send a request using both campaignId and source, the message will be rejected.

Required: yes

Default: no default

Type: string

note1

Use this when you want to add data, such as individual identifiers (e.g. your own transaction, ticket, or system IDs), which can then be included in reports. It has no effect on the message or its delivery. The value is free-form text 0-200 characters in length.

This value is included in the SMS Detailed report and returned in delivery receipts.

Required: no

Default: no default

Type: string

note2

Identical to note1.

Required: no

Default: no default

Type: string

destination object

Object that contains details about the message recipient (the end user's details).

This object is required.

Member

Description

address

The phone number to which you are sending an SMS message.

This must be a phone number that includes the country code. Do not include the "+" character. For example:

  • 12125550123 (US number)
  • 447700900750 (UK number)
  • 61491570156 (Australian number)

The length must be between 5 to 20 digits.

Required: yes

Type: string

mobileOperatorId

An OpenMarket-specific number that identifies the mobile operator to which OpenMarket should route the message.

You can include mobileOperatorId when you are sending a message using a US or Canada short code, toll-free number, or landline number. It is optional because we will perform an operator lookup if you do not supply a value. Depending on your contract with OpenMarket, you may be charged for each lookup.

Do not include mobileOperatorId when you are sending global messages, or sending using a US or Canadian virtual mobile number (VMN). OpenMarket ignores the value and performs a dynamic operator lookup for these messages. You are not charged for these lookups.

For a list of valid mobile operators IDs, see Mobile Operator IDs.

Required: no

Default: OpenMarket performs an operator lookup.

Type: integer

 

message object

Object that contains details about the message you are sending.

This object is required.

Member

Description

type

Identifies what type of message you are sending. For branded messages, specify the type as 'text.'

For text messages, it also identifies whether you are sending the message contents to us as plain text or hex-encoded text.

  • text — Message is in UTF-8

The values are case-sensitive.

Required: yes

Type: string

content

The message sent to the end user's phone. For branded messages the content type must be plain text sent in UTF-8.

Alphanumeric string that is between 1 to 2680 bytes in size.

Required: yes

Type: string

validityPeriod

Specifies the period (in seconds) that OpenMarket and mobile operators will attempt to deliver the message. You can specify a number between 1 and 259200.

Required: no

Default: no default. OpenMarket and the mobile operator use their standard retry strategies.

Type: number

delivery object

Optional object for receiving delivery receipts. If you do not include this object then you will not receive delivery receipts for the message.

Member

Description

receiptRequested

Indicates that you want to receive a delivery receipt for the message. OpenMarket will send the delivery receipt when the mobile operator sends us a final delivery state.

The value is case-sensitive.

Required: yes

Type: string; only valid value is final.

url

The URL to which you want us to send delivery receipts.

The value must be between 12 to 2048 characters. The URL must begin with the protocol, https:// or http://.

Required: no

Default: We send the delivery receipt to the URL specified during your account provisioning. If there is no provisioned URL, then we do not send a delivery receipt.

Type: string

Response from OpenMarket

Accepted requests

If your request is accepted then OpenMarket sends an HTTP 202 response, with the following information in the header.

HTTP/1.1 202 Accepted
Server: Apache-Coyote/1.1
Location: https://smsc.openmarket.com/sms/v4/mt/03155-0331L-1439U-51SLFX
X-Request-Id: 001-3-72879E62-6586-4F77-9E7B-1E74386F0223
Content-Type: application/json;charset=UTF-8
Content-Length: 0
Date: Tue, 31 Mar 2015 18:39:51 GMT
Connection: close

The response body is empty.

Header fields

Field

Description

X-Request-Id

A unique ID that identifies the specific request you made in OpenMarket's systems.

This ID is logged in our systems and is useful if you need to query the request with OpenMarket Support at a later date.

Returned: always

Type: case-insensitive string up to 45 characters in length

Location

The URI for the message resource. The last part of the URI path is a ticket ID; e.g.:

https://smsc.openmarket.com/sms/v4/mt/<ticket ID>

You will need the ticket ID when querying the status of an SMS message, and to identify the correct delivery receipt for a message. This ID is also passed to reporting and is useful if you need to query message activity with OpenMarket support.

Returned: always

Type: string, maximum length of 23 characters

Rejected requests

If your request is rejected then the body of the response will contain a code that identifies the error. For example:

HTTP/1.1 400 Bad Request
Server: Apache-Coyote/1.1
X-Request-Id: 001-1-761372B6-EE31-427E-AEB4-ED9E88CDD7A6
Content-Type: application/json;charset=UTF-8
Date: Tue, 13 Oct 2015 21:01:59 GMT
Connection: close
					
{
"error":{
   "code":"540",
   "description":"Invalid request - destination address is required"
   }
}

Header fields

Field

Description

X-Request-Id

A unique ID that identifies the specific request you made in OpenMarket's systems.

This ID is logged in our systems and is useful if you need to query the request with OpenMarket Support at a later date.

Returned: always

Type: case-insensitive string up to 45 characters in length

Response body

The response body will contain one object, error.

Member

Description

code

Code defining the reason for the outcome of the request. For a list of the codes, see Response error codes below.

Returned: always for rejected requests

Type: string

description

Description of the error.

Returned: always for rejected requests

Type: string

Testing your integration

You can send test SMS messages to the OpenMarket Customer Integration Environment (CIE) to test your integration. Test messages are not delivered to any end user devices. They're delivered only to our platform to test that messages contain the required information and are formatted properly.

See Testing your integration with OpenMarket.

Troubleshooting

I didn't receive a synchronous reply back - should I retry the request?

If you receive an HTTP transaction timeout, it is still possible that we received the request. Therefore, you should decide whether you'd prefer the end user to potentially receive the message twice, or to not receive the message at all.

There are a lot of 540 error codes - what do they mean?

We use the 540 code when there is an issue with the format or syntax of your request. The code description will provide a reason. This may be because:

  • You are missing a required object.
  • The value for a JSON name-value pair is invalid; for example, it is misspelled, too long or short, is supposed to be a Boolean or number value, or includes characters not allowed in the value.

Why did I receive an HTTP 415 status code?

This refers to the Content-Type field that is specified in the header. You must include this header in your requests. For JSON requests, set this to application/json.

We don't return a separate OpenMarket response error code in the body for this type of error.

Response error codes

These codes are returned in the response body when there was a problem with receiving the request.

OpenMarket and HTTP API response error codes

This table describes OpenMarket response codes and corresponding HTTP response codes.

OpenMarket error code

HTTP status code

Error description

Notes

352 400 Invalid request - destination address country code is not recognized. OpenMarket does not recognize the address country code passed in the request. Check that you are using the correct code.

420

401

Invalid account ID or account password

The authentication details you sent in the requests do not match, or do not exist. Check that your account ID and password are base 64-encoded, and have a colon between them; e.g.:

123-123-123-12345:Secure123

Encodes to:

MTIzLTEyMy0xMjMtMTIzNDU6U2VjdXJlMTIz

431

403

Account not provisioned for SMS

We recognized your account, but it is not provisioned for SMS messaging.

Talk to your OpenMarket account manager to provision SMS messaging.

432

403

Account blocked for SMS

Your OpenMarket account is blocked from sending SMS messages.

Talk to your OpenMarket account manager for more information.

540

400

Invalid request - mobileOperatorId value is invalid

The mobileOperatorId you specified had a non-numeric character.

540

400

Invalid request - destination address value is invalid

There is a problem with the value for destination address:

  • There is no value specified
  • The value is less than 5 characters or greater than 20 characters in length
  • The value contains a non-numeric character, like a plus sign, e.g.: "+447700900765"

You must ensure that end user's phone numbers have a country code, and don't include include any additional symbols or letters, e.g.: "447700900765" (UK number) or "12515550145" (US number).

540

400

Invalid request - destination address is required

Your request is missing destination address.

540

400

Invalid request - message content must have a value

You did not include a value for content in your request. The value must be a minimum of 1 byte.

540

400

Invalid request - message content exceeds 2680 bytes

You specified a value for content that is more than the maximum value of 2680 bytes.

540

400

Invalid request - message content value is invalid

This error occurs when the message type is hexEncodedText and we cannot interpret the message content. This may be because the value for charset is incorrect. For example, if you specify Latin-1, then you will get this error if you instead use UTF-16.

540

400

Invalid request - mlc value is invalid

You specified a value for mlc that is not one of the valid options. Values are case-sensitive.

540

400

Invalid request - promotional value is invalid

You included promotional in your request. The value for this must be either true or false.

540

400

Invalid request - source ton value is invalid

You specified a value that is not valid for the source ton. This must be a number, one of: 1,3 or 5.

540

400

Invalid request - source address value is invalid

Occurs when you have included source in your request and:

  • You did not include a source address
  • You specified a ton of 1 or 3, and your source address is an alphanumeric string (or contains an extra character, such as a "+" sign)
  • Your source address is greater than the maximum of 20 characters

540

400

Invalid request - type value is invalid

You specified a value for type that is not one of the valid options. Values are case-sensitive.

540

400

Invalid request - charset value is invalid

You specified a value for charset that is not one of the valid options. Values are case-sensitive.

540

400

Invalid request - wapPush url value is invalid

You specified that the message is type of wapPush; however, either:

  • url is missing from the request
  • The value of url is invalid (we do some basic URL validation)
  • The length is smaller than 12 characters or greater than 2048 characters

540

400

Invalid request - validityPeriod value is invalid

You specified a value for validityPeriod that is more than the maximum value of 259200, or you have included non-digits in the value.

540

400

Invalid request - invalid XML in the payload

OR

Invalid request - invalid JSON in the payload

Your request body is either missing, or we cannot parse the XML/JSON in the body.

540

400

Invalid request - message is required

Your request is missing the message object/element.

540

400

Invalid request - note1 value is invalid

You specified a value for note1 that is more than the maximum value of 200 characters.

540

400

Invalid request - note2 value is invalid

You specified a value for note2 that is more than the maximum value of 200 characters.

540

400

Invalid request - programId value is invalid

You specified a value for programId that is longer than the 50 characters (the maximum character length).

540

400

Invalid request - flash value is invalid

The value for flash can only be either true or false.

540

400

Invalid request - udh value is invalid

The value for udh can only be either true or false.

540

400

Invalid request - receiptRequested is required as the request includes delivery

Your request included the delivery object/element. When this is included you must also include receiptRequested.

540

400

Invalid request - receiptRequested value is invalid

You specified a value for receiptRequested that is not one of the valid options.

540

400

Invalid request - delivery URL value is invalid

Inside the delivery object/element, the value for URL is either: Not a correctly formatted URL—for example example, you must include http:// or https:// in the URL, or gGreater than the maximum of 2048 characters.

540

400

Invalid request - interaction value is invalid

You specified a value for interaction that is not one of the valid options.

592

403

Account not provisioned for global one- or two-way SMS

The end user's number has a country code that is from a region of the world that you are not provisioned to reach. For example, if you exclusively message in the US or CA, you will not be provisioned for messaging end users who reside in other regions.

If you'd like extend your messaging to reach end users globally, please contact your OpenMarket account manager.

Retryable: no

594 400 Invalid campaign ID Returned only for branded message requests. The campaignId in the request is either not configured in our system or is inactive. Contact your OpenMarket account manager for help.

1000

5xx

Temporary error processing request

This error is returned when OpenMarket is temporarily unable to finish processing the request. We may have sent the message on to the mobile operator. Therefore we recommend not retrying your request if you receive this error more than once, and contact OpenMarket Support if you continue to receive this error.

1010

5xx

Temporary system error

This error is returned when OpenMarket is temporarily unable to process requests. Retry your request in intervals of 10 seconds or more, and contact OpenMarket Support if you continue to receive this error.