---
schema_version: "1"
id: 1ab09c61aa468e1360389a9149ae06c4b805a33c9bafc67a2f2e685f3f24d800
title: Use the MobileConnect API
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/guides/mc-apis/using-the-mobileconnect-api.md
canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/using-the-mobileconnect-api.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 073ca648d2119ca242ebccc21e3aea9f41f4f0880ad7692e861801623296117d
products:
  - Marketing Cloud Engagement APIs and Programmatic Languages
  - Marketing Cloud
---
# Use the MobileConnect API

## Subscribe Mobile Numbers to a Short Code

Delivery of an outbound SMS message through the MobileConnect application requires an active short code and keyword subscription. MobileConnect assists marketers and developers with the creation of message subscriptions through the SMS Opt-In template.

MobileConnect supports three variations of the SMS Opt-In:

1.  Single Opt-In: Contact texts JOIN (or another specified keyword) to your short code to subscribe to a specified keyword on that short code.
2.  Double Opt-In: Contact texts JOIN (or another specified keyword) to your short code and receives a text message asking them to reply Y or YES to confirm their subscription. Upon replying Y or YES, MobileConnect subscribes the contact to the specified keyword on that short code.
3.  Double Opt-In with Age Confirmation: Contact texts JOIN (or another specified keyword) to your short code, the contact reply to the initial confirmation messag,e and confirm with their birth date before subscribing to the specified keyword on that short code.

**warning:** CTIA and MMA best practices state that SMS subscriptions originating from a web form or mobile app must use the Double Opt-In variation. Use the MobileConnect QueueMO REST API to replicate the original inbound text of JOIN. This way, the contact will only receive one text message that requires replying with Y or YES to finalize creation of the subscription.

![Create New Message: Template Selection](https://developer.salesforce.com/docs/media/images/MobileConnect_2.png)

![Select Template: Define Content](https://developer.salesforce.com/docs/media/images/MobileConnect_3.png)

![Messages Options with Acceptance, Confirmation, and Opt-in Error Messages](https://developer.salesforce.com/docs/media/images/MobileConnect_4.png)

## Example QueueMO API Request

```js
POST `https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com/sms/v1/queueMO`
Content-Type: application/json
Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN
{
  "mobileNumbers": [
    "15555551212"
  ],
  "shortCode": "Code",
  "messageText": "KEYWORD"
}
```

Key:

- `mobileNumbers` includes the mobile number to subscribe
- `shortCode` includes the SMS short code used in the SMS Opt-In template
- `messageText` contains the keyword used in the SMS Opt-In template

## Confirm Subscription Status in MobileConnect

Once you create an SMS Opt-In message, ensure that MobileConnect creates the subscriptions correctly.

1.  Navigate to the MobileConnect overview screen.
2.  Open the Contacts application.
3.  Click **Manage** under Contacts.
4.  Search for the specific mobile number.
5.  Click the mobile number.
6.  Click **Subscriptions**.
7.  Confirm the subscription status of **Subscribed**. MobileConnect only delivers outbound SMS messages to mobile numbers that maintain a **Subscribed** status for the specified short code. Mobile numbers with an **In Progress** status haven’t completed the Double Opt-in process and don’t receive SMS messages.

![Confirm the Subscription Status](https://developer.salesforce.com/docs/media/images/MobileConnect_5.png)

Insider Tip: You built a mobile app, now you need users. The expectation that contacts will see your sign promoting the app, take out their phone, open the App Store or Google Play, search for your app, and finally download your app represents only part of your overall plan. Allow consumers to request a link to download your app via SMS. For example, “Text SMCAPP to (your short code) to download the mobile app.” When a contact texts SMCAPP to your short code, that contact will receive a text message containing a link to your app in the App Store or Google Play. Create this message with the MobileConnect Text Response template.

## Trigger SMS Messages from a Mobile App

Once you build a mobile app and subscribe contacts to your short code and keyword, you can deliver SMS messages. Use the MobileConnect Outbound message template to define the content for each message. Follow these steps to create your message:

1.  Name the message.
2.  Select the short code to be used for delivery. Use the same code on which contacts subscribed to a specific keyword.
3.  Select the **API Trigger** send method.
4.  Define message content. Both the MessageContact and MessageList APIs allow for override of defined message content.
5.  Activate your message. Both the messageContact and messageList request bodies use the API key received during this step.

![Selecting the Outbound Template](https://developer.salesforce.com/docs/media/images/MobileConnect_6.png)

![Creating the New Message for the Outbound Template](https://developer.salesforce.com/docs/media/images/MobileConnect_7.png)

![Confirm to Activate the Message](https://developer.salesforce.com/docs/media/images/MobileConnect_8.png)

## Example messageContact API Request

```js
POST https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com/sms/v1/messageContact/MzA6Nzg6MA/send
Content-Type: application/json
Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN
{
  "mobileNumbers": [
    "13175551212"
  ],
  "Subscribe": false,
  "Resubscribe": false,
  "Override": true,
  "messageText": "Welcome to Code@"
}
```

If you wish to ensure that the contact exists for the specified mobile number and that the mobile number subscribed to the specified keyword for your API message, set the `Subscribe` and `Resubscribe` values to `true`, as shown in the example below.

```js
POST https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com/sms/v1/messageContact/MzA6Nzg6MA/send
Content-Type: application/json
Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN
{
    "mobileNumbers": [
    "13175551212"
    ],
    "Subscribe": true,
    "Resubscribe": true,
    "Override": true,
    "messageText": "Welcome to Code@",
}
```

Key:

- `Override` allows for the override of message content defined within the MobileConnect UI
- `messageText` defines message content if Override = true

## Deliver On-Demand SMS Content with Text Response

SMS allows for two conversations initiated by consumers. Use the MobileConnect Text Response template to create content sent to consumers in response to an SMS message to your short code. For example: “Text STOCK to (your short code) to get a real-time quote of Brand ABC stock price.”

![Selecting a Test Response Template](https://developer.salesforce.com/docs/media/images/MobileConnect_9.png)

![Setup for the Test Response Template](https://developer.salesforce.com/docs/media/images/MobileConnect_10.png)

## Example Message Content for STOCK Use Case

```js
%%[
Set @mobile = v([MOBILE_NUMBER])
Set @mobile1 = Substring(@mobile,2,10)
Set @keyword = v([MSG(0).VERB])
set @noun = lowercase([MSG(0).NOUN(0)])
set @url = Concat("http://finance.example.com/d/quotes.csv?s=CRM&f=snd1l1yr",@mobile1,"&alert_keyword=",@keyword)
set @msg = [MSG(0)]Set @message = HttpGet(@url)]%%
example.com Stock is: %%=ProperCase(@message)=%% Thanks for Responding!
```

![Setting the Response Messsage](https://developer.salesforce.com/docs/media/images/MobileConnect_11.png)

## Most Common MobileConnect REST APIs

### messageContact

[Send an SMS message to up to 250 MobileConnect subscribers](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/postMessageContactSend.md). Use cases include appointment reminders, account alerts, itinerary updates, and other direct communications.

### MessageList

[Send an SMS message to an identified MobileConnect List](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/postMessageList.md). Use cases include daily promotions overview, app update available notifications, and other broad communications.

### queueMO

[Replicate an inbound SMS message from a mobile device](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/postQueueMO.md). Use as part of a Double Opt-in process via web form or mobile app.

Visit the [SMS REST API reference page](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/routes.md) to learn about all of the REST APIs supported by MobileConnect.