v3 SMS HTTP
Note: If you're new to OpenMarket, then integrate with our Global SMS (version 4) operations.
Customers currently integrated using v3 may continue to use it, although we encourage customers to migrate to v4 in order to take advantage of new features. Please also note that there are no SDKs available for either version of the Global SMS API.
You may need to configure your requests based on the region you are messaging. This is split into the following:
The differences in your request settings are highlighted below.
If you decide to begin messaging another regions, make sure you contact your OpenMarket account manager first, as we will need to give your account access to each country, and determine whether you need any numbers provisioned for two-way messaging.
International
When sending international messages:
- carrier — do not include the carrier ID when submitting international MTs. Carrier routing is determined dynamically. You will not be charged for a dynamic carrier look-up.
- charge_type — Set this to 20.
International one-way example request
<?xml version="1.0" ?>
<request version="3.0" protocol="wmp" type="submit">
<user agent="Java/SMS/1.1.10"/>
<account id="983-000-000-54321" password="ABCD1234"/>
<option charge_type="20"/>
<source ton="5" address="MYBRAND"/>
<destination ton="1" address="44123456789"/>
<message udhi="false" text="Hello World"/>
</request>International two-way example request
<?xml version="1.0" ?>
<request version="3.0" protocol="wmp" type="submit">
<user agent="Java/SMS/1.1.10"/>
<account id="983-000-000-54321" password="ABCD1234"/>
<option charge_type="20"/>
<source ton="1" address="44987654321"/>
<destination ton="1" address="44123456789"/>
<message udhi="false" text="Hello World"/>
</request>United States and Canada
US and Canada requires a provisioned message originator, and a firm understanding of the US and Canadian regulatory and best practice guidelines. For message originators, you have the following options:
- Short codes
- Virtual mobile numbers (VMNs)
- Toll-free numbers
- Landline numbers
OpenMarket can help you provision your message originators. During provisioning, you will need to provide a program brief to show that your campaigns met local regulations and operator requirements, which we can help you with. To get started, contact your OpenMarket account manager.
For a list of the mobile operators that support text-enabled landlines and toll-free numbers, see Mobile Operator IDs.
Sending using a short code
When sending using a short code:
- source ton— set the TON to 3
- carrier — You can choose to submit this. If you don't OpenMarket will perform an Operator Lookup on your behalf, which you may be charged for.
- charge_type — set to 0.
- program_id — Specify the provisioned program associated with a short code for a given mobile operator.
Example request
<?xml version="1.0" ?>
<request version="3.0" protocol="wmp" type="submit">
<user agent="XML/SMS/1.0" />
<account id="123-456-789-12345" password="your password" />
<option charge_type="0" program_id="ABC" />
<source ton="3" address="54321" />
<destination carrier="383" ton="1" address="12125551212" />
<message text="Hello World!" />
</request>Sending using a US virtual mobile number
When sending using a virtual mobile number, you will need to provide a program brief; however, you do not need to pass in a program ID in your request. In your request:
- source ton — set the TON to 1
- carrier — do not include a carrier ID when submitting MTs from US VMNs. Carrier routing is determined dynamically. You will not be charged for a dynamic carrier look-up. If you submit a carrier ID it will be ignored.
- charge_type — set to 0.
Example request
<?xml version="1.0" ?>
<request version="3.0" protocol="wmp" type="submit">
<user agent="XML/SMS/1.0" />
<account id="123-456-789-12345" password="your password" />
<option charge_type="0" />
<source ton="1" address="13132021010" />
<destination ton="1" address="12125551212" />
<message text="Hello World!" />
</request>Note: Receiving SMS messages — OpenMarket does not identify the mobile operator in MOs sent to a US VMN. The carrier_id parameter is set to zero (0). Message data contains hexadecimal-encoded GSM characters.
Sending using an SMS-enabled toll-free and landline numbers
When sending using a toll-free or landline number, you will need to provide a program brief; however, you do not need to pass in a program ID in your request. In your request:
- source ton — Set source TON to 1
- carrier — You can choose to submit this. For toll-free numbers, if you don't include the ID then OpenMarket performs an Operator Lookup on your behalf, for which you may be charged.For landline numbers, we do not need to perform the lookup (so you will not be charged).
- charge_type — set to 0.
Example request
<?xml version="1.0" ?>
<request version="3.0" protocol="wmp" type="submit">
<user agent="XML/SMS/1.0" />
<account id="123-456-789-12345" password="your password" />
<option charge_type="0" />
<source ton="1" address="13132021010" />
<destination carrier="383" ton="1" address="12125550123" />
<message text="Hello World!" />
</request>For a list of mobile operators supporting toll-free and landline messaging, see Mobile Operator IDs.
India
In India, you must set a purpose for the message; either transactional or promotional, to conform to the local regulations.
You can send transactional messages to end users at any time of day, and messages can be one-way or two-way. An example might be messages advising about delivery of ordered goods. You cannot use transactional messages for marketing or promotional material.
Use a six-character alphabetic source address (message originator) for your transactional MT messages. Make sure to contact either OpenMarket Support or your account manager with the source addresses you intend to use for your service so that we can provision them.
You can deliver promotional messages to end users between 9:00 a.m. and 9:00 p.m. India time. If you submit promotional messages to OpenMarket outside of this period, the messages will be queued to the next allowable time.
Use any six-character alphabetic MT source address. You do not need to notify OpenMarket about the source addresses for promotional messages. Mobile operators in India replace the MT source address you provide with a random six-digit source address before the MT is sent to the end user.
Also, in your request:
- carrier — do not include the carrier ID. Carrier routing is determined dynamically. You will not be charged for a dynamic carrier look-up.
- charge_type — Set this to 20.
Example transactional message request
<?xml version="1.0" ?>
<request version="3.0" protocol="wmp" type="submit">
<user agent="SMS/1.1.10"/>
<account id="myaccount" password="ABCD1234"/>
<option charge_type="20" purpose="transactional" />
<source ton="5" address="MYCORP"/>
<destination ton="1" address="919000000000"/
<message udhi="false" text="If you have received your order from CompanyA order number 49275, reply Yes to 919000000210."/>
</request>