US 10DLC API Installation

A quick start to install a US 10 DLC number

To setup a new channel to send SMS messages using a United states 10 digit long code number the following steps are required

API Access

The following API requests can only be made using a valid access key and attached to an access role with the an access policy that at least specifies the permissions to the resources outlined in each section below.

Find an available number

If you do not already have a US 10DLC number available in your workspace you can find one to purchase .You can filter by country, prefix, number type and number capabilities.

Example

Request

The following example will return the first available US local number required for use with 10DLC registration.

curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/numbers-available?limit=1&country=US&type=local' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>'

Purchase a number

Once you have found an available number, you can purchase it by providing the number (using the unique identifier provided by the endpoint above).

A successful request to this endpoint will start a recurring monthly subscription based on the monthly cost of the number

Register a new brand with the campaign registry

A-Sync : this will start a background process that may require some time to complete. A Get call may be required to to retrieve the final result .

After creating a brand, this will be submitted for approval by the campaign registry. The brand must be approved before you can register a campaign with the campaign registry. Brand registration may take some time.

You can find the full list of brand management endpoints here

Request

The following example will create a new brand that will be submitted for registration with the campaign registry.

curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/tcr-brands' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>' \
--data '{
  "entityType": "",
  "firstName": "",
  "lastName": "",
  "displayName": "",
  "companyName": "",
  "ein": "",
  "einIssuingCountry": "",
  "phone": "",
  "street": "",
  "city": "",
  "state": "",
  "postalCode": "",
  "country": "",
  "email": "",
  "stockSymbol": "",
  "stockExchange": "",
  "website": "",
  "vertical": "",
  "altBusinessId": "",
  "altBusinessIdType": ""
}

(Optional) Submit brand for external vetting

A-Sync : this will start a background process that may require some time to complete. A Get call may be required to to retrieve the final result .

The final result of If your brand is not being accepted or your company is not part of the Russell 3000 stock index you can also request additional vetting. For brands that are not part of the Russell 3000 stock index this can provide access to higher messaging throughputs (depending on your vetting score)

Request

The following example will create a new brand vetting request that will be submitted for registration with the campaign registry. You must have previously created a brand

curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/tcr-brands/<your-brand-id>/vettings' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>' \
--data '{
  "class": "STANDARD",
  "vettingProviderId": "AEGIS"
}

Register a new campaign with the campaign registry

To reduce the likelihood of rejection, ensure you are familiar with 10dlc registration examples and best practices. Specifically

• Check this article for tips on how to write an effective Campaign description

• Check this article on how to write an effective messageFlow

Most 10DLC rejections are caused by unclear or incomplete description and/or messageFlow

A-Sync : this will start a background process that may require some time to complete. A Get call may be required to to retrieve the final result .

After creating a campaign, this will be submitted for approval by the campaign registry. The campaign must be approved before you can associate this with an SMS channel. Campaign registration can take 1-2 weeks to be approved.

You can find the full list of campaign management endpoints here

Request

The following example will create a new campaign that will be submitted for registration with the campaign registry. Your associated brand must be approved

curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/tcr-brands/<your-brand-id>/campaigns' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>' \
--data '{
  "name": "TEST",
  "usecase": "LOW_VOLUME",
  "subUsecases": [
    "MARKETING",
    "DELIVERY_NOTIFICATION",
    "2FA"
  ],
  "description": "Internal use case for TEST ONLY",
  "embeddedLink": false,
  "embeddedPhone": false,
  "numberPool": false,
  "ageGated": false,
  "directLending": false,
  "subscriberOptin": true,
  "subscriberOptout": true,
  "subscriberHelp": true,
  "samples": [
    "This is a TEST MESSAGE"
  ],
  "messageFlow": "this is an internal use case. They will only send to their own device and will not send to any external users. External users will only see SMS via screen-sharing during live or recorded demos.",
  "helpMessage": "send HELP to be connected to support",
  "helpKeywords": "HELP",
  "optoutKeywords": "STOP",
  "optinKeywords": "START",
  "optinMessage": "send Start to enable notifications and messages.",
  "optoutMessage": "send STOP to unsubscribe",
  "termsAndConditions": true
}'

Install a channel connector

A-Sync : this will start a background process that may require some time to complete. A Get call may be required to to retrieve the final result .

Request

The following example will create a new SMS connector with an approved 10DLC campaign and US local number:

curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/connectors' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>' \
--data '{
    "connectorTemplateRef": "sms-messagebird:1",
    "name": "SMS channel",
    "arguments": {
        "phoneNumberId": "",
        "useCaseId": "",
        "channelMessageType": "",
    },
    "channelConversationalStatusEnabled": true
}

Arguments

Get your channel id

Once you have created your SMS connector, this will create an SMS channel. You can then get your channel ID to before setting up channel webhooks

Request

The following example will get the connector you have created in the previous step. Parse the channel.channelId to get the id of your new SMS channel

curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/connectors/<your-connector-id>' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>'

Setup channel message webhooks

Once your channel has been installed you will then need to setup a webhook subscription to receive status updates and inbound messages

Request

The following request example will create a new SMS subscription for inbound and outbound messages

Inbound messages

curl --location 'https://api.bird.com/organizations/<your-organization-id>/workspaces/<your-workspace-id>/webhook-subscriptions' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>' \
--data '{
    "signingKey": "my-signing-key",
    "eventFilters": [
        {
            "key": "channelId",
            "value": "<your-channel-id>"
        }
    ],
    "event": "sms.inbound",
    "service": "channels",
    "url": "<your-webhook-url>"
}'

Outbound messages

curl --location 'https://api.bird.com/organizations/<your-organization-id>/workspaces/<your-workspace-id>/webhook-subscriptions' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>' \
--data '{
    "signingKey": "my-signing-key",
    "eventFilters": [
        {
            "key": "channelId",
            "value": "<your-channel-id>"
        }
    ],
    "event": "sms.outbound",
    "service": "channels",
    "url": "<your-webhook-url>"
}'

Arguments

Confirm a 10DLC Channels Readiness to send SMS traffic

A-Sync : this will start a background process that may require some time to complete. A Get call may be required to retrieve the final result

10DLC numbers can only send traffic to the USA when linked to a campaign. Number Campaign link is an A-sync process requiring confirmations from multiple carriers.

The bird will only consider a number linked if all major USA carriers acknowledge the links. Delays in carrier acknowledgment can vary between 15 minutes to several hours and are usually longer around peak linking hours (afternoon/evening USA Pacific time)

Linking will trigger the connector status field "useCaseStatus" to turn to "ok"

The channel cannot terminate SMS to the USA

This could happen if the number linked to its campaigns is not acknowledged or the 10DLC registration experiences issues. In this case, the "useCaseStatus" 's value will not be "ok"

"name": "useCaseStatus",
                "displayName": "UseCase Status",
                "assertions": [
                    {
                        "name": "brand",
                        "displayName": "",
                        "description": "",
                        "status": "ok"
                    },
                    {
                        "name": "campaign",
                        "displayName": "",
                        "description": "",
                        "status": "ok"
                    },
                    {
                        "name": "checks whether number is linked to campaign",
                        "displayName": "",
                        "description": "",
                        "status": "warning",
                        "message": "Number status is INACTIVE"
                    }
                ],
                "status": "warning"

The channel can terminate messages to the USA

In this case "useCaseStatus" will be "ok"

"name": "useCaseStatus",
                "displayName": "UseCase Status",
                "assertions": [
                    {
                        "name": "brand",
                        "displayName": "",
                        "description": "",
                        "status": "ok"
                    },
                    {
                        "name": "campaign",
                        "displayName": "",
                        "description": "",
                        "status": "ok"
                    },
                    {
                        "name": "checks whether number is linked to campaign",
                        "displayName": "",
                        "description": "",
                        "status": "ok"
                    }
                ],
                "status": "ok"
```