Create a campaign
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 successful request to this endpoint will mean you are charged a campaign registration fee and a three-month minimum commitment fee. If you later need to update or resubmit your brand there may be additional fees.
- You must have created a brand that has been approved, before creating a new campaign
- If you operate as a Reseller ensure your Reseller registration is active before using the reseller field in POST campaigns
Handling Attachments
You will need to attach proof of opt-in and/or consent collection. To facilitate troubleshooting by both your team and the Bird team, we strongly recommend including a URL (e.g., to a third-party hosting service like Google Drive) directly in the messageFlow JSON field.
Note: The attachment vector is only supported via the UI and is not currently supported via API POST requests.
POST
/workspaces/{workspaceId}/tcr-brands/{brandId}/campaigns
To create a campaign, it is essential to ensure that the brand has already been approved. Campaigns can only be initiated under the umbrella of brands that meet this prerequisite. Once a campaign is created, it cannot begin directing traffic immediately. Instead, it must go through a formal approval process. Only after the campaign has been reviewed and approved it will be authorized to send traffic.
Attachments: You can include up to 5 file attachments (max 10MB each) by providing URLs in the attachmentUrls field. Both internal media service URLs and external URLs (e.g., Azure Blob Storage, AWS S3) are supported. External files are automatically downloaded and uploaded to the media service.
请求载荷
name
string
必填
Campaign name
usecase
string
必填
A use case that best matches the purpose of the campaign.
subUsecases
array of string
If use case is MIXED or LOW_VOLUME mixed an array of 2-5 use cases.
description
string
必填
A detailed description of what the campaign is for.
embeddedLink
boolean
Whether messages will contain links. Provide at least one sample containing a link.
embeddedPhone
boolean
Whether messages will contain phone number. Provide at least one sample containing a phone number.
numberPool
boolean
Whether a campaign will be associated with more than 50 numbers e.g. customer service use case.
ageGated
boolean
Whether a campaign contains age-gated content based on carrier/ctia guidelines.
directLending
boolean
Whether a campaign includes content related to direct lending or loan arrangements.
subscriberOptin
boolean
Confirm customer opt in is collected and processed.
subscriberOptout
boolean
Confirm customer opt out is collected and processed.
subscriberHelp
boolean
Confirm an info message is returned if a customer sends "HELP".
samples
array of string
必填
Between 1-5 sample messages, each 20-1024 characters. If directLending, embeddedPhone, embeddedLink is true provide relevant examples.
attachmentUrls
array of string
Up to 5 attachment URLs (max 10MB each). Supports both internal media service URLs and external URLs.
Internal URLs: Obtained via POST /workspaces/{workspaceId}/tcr-brands/{brandId}/pre-signed-upload
External URLs: Any publicly accessible HTTPS URL (e.g., Azure Blob Storage, AWS S3). External files are automatically downloaded and uploaded to the media service.
Examples:
- https://channels.messagebird.com/v1/media/temp/abc123 (internal)
- https://mybucket.blob.core.windows.net/files/consent.pdf?signature=... (external)
messageFlow
string
必填
Provide details of how the customer will opt into this campaign. If you have a live web opt-in provide the URL and ensure the page has details on the T&Cs/data collection for opting in, and how to opt out.
helpMessage
string
必填
Help message of the campaign. A help message shall state the name of the service, contact (email or call centre), OPT IN and OPT OUT keywords.
helpKeywords
string
A comma separated list of keywords. Support of the word HELP is the minimum requirement for requesting help/info.
optoutKeywords
string
A comma separated list of keywords. Support of the word STOP is the minimum requirement for OPT OUT.
optinKeywords
string
A comma separated list of keywords. Support of the word START is the minimum requirement for OPT OUT.
optinMessage
string
Provide an example of the message that will be sent after a customer has opted in.
optoutMessage
string
Provide an example of the message that will be sent after a customer has opted out.
termsAndConditions
boolean
必填
Indicates the campaign follows CTIA messaging principles and best practices.
Possible values: true
resellerId
string
UUID of the reseller associated with this campaign. The specified reseller MUST be ACTIVE.
响应载荷
id
string
UUID of the campaign.
name
string
Campaign name
subscription
object
Describes status of Campaign Subscription
显示子属性
subscription.status
string
Possible values: active, inactive, canceling
subscription.subscribedAt
string
Timestamp (UTC) when the subscription became active.
subscription.updatedAt
string
Timestamp (UTC) when the subscription was last updated.
subscription.cancelledAt
string
Timestamp (UTC) when the subscription was cancelled.
status
string
Campaign status
Possible values: DRAFT, FAILED, PENDING, REJECTED, APPROVED, DECLINED, SUSPENDED, DELETED, EXPIRED
usecase
string
A use case that best matches the purpose of the campaign.
subUsecases
array of string
If use case is MIXED or LOW_VOLUME mixed an array of 2-5 use cases.
description
string
A detailed description of what the campaign is for.
embeddedLink
boolean
Whether messages will contain links. Provide at least one sample containing a link.
embeddedPhone
boolean
Whether messages will contain phone number. Provide at least one sample containing a phone number.
numberPool
boolean
Whether a campaign will be associated with more than 50 numbers e.g. customer service use case.
ageGated
boolean
Whether a campaign contains age-gated content based on carrier/ctia guidelines.
directLending
boolean
Whether a campaign includes content related to direct lending or loan arrangements.
subscriberOptin
boolean
Confirm customer opt in is collected and processed.
subscriberOptout
boolean
Confirm customer opt out is collected and processed.
subscriberHelp
boolean
Confirm an info message is returned if a customer sends "HELP".
samples
array of string
Between 1-5 sample messages, each up to 1024 characters (empty until the campaign is submitted). If directLending, embeddedPhone, embeddedLink is true provide relevant examples.
messageFlow
string
Provide details of how the customer will opt into this campaign. If you have a live web opt-in provide the URL and ensure the page has details on the T&Cs/data collection for opting in, and how to opt out.
helpMessage
string
Help message of the campaign. A help message shall state the name of the service, contact (email or call centre), OPT IN and OPT OUT keywords.
helpKeywords
string
A comma separated list of keywords. Support of the word HELP is the minimum requirement for requesting help/info.
optoutKeywords
string
A comma separated list of keywords. Support of the word STOP is the minimum requirement for OPT OUT.
optinKeywords
string
A comma separated list of keywords. Support of the word START is the minimum requirement for OPT OUT.
optinMessage
string
Provide an example of the message that will be sent after a customer has opted in.
optoutMessage
string
Provide an example of the message that will be sent after a customer has opted out.
termsAndConditions
boolean
Indicates the campaign follows CTIA messaging principles and best practices.
brandId
string
UUID of the brand associated with this campaign. The specified brand MUST be APPROVED.
resellerId
string
UUID of the reseller associated with this campaign. The specified reseller MUST be ACTIVE.
rejection
object
Rejection details
显示子属性
rejection.description
string
必填
Rejection description
rejection.code
string
Rejection code
attachments
array of object
Attachments associated with this campaign.
显示子属性
attachments.id
string
必填
The ID of the attachment.
attachments.status
string
必填
Attachment status
Possible values: PENDING, ACTIVE, PENDING_DELETION, DELETED, FAILED, FAILED_DELETION
attachments.createdAt
string
必填
Timestamp (UTC) when the attachment was created.
attachments.updatedAt
string
必填
Timestamp (UTC) when the attachment was last updated.
attachments.filename
string
必填
The original name of the file when it was uploaded.
attachments.mediaUrl
string
The URL to download the attachment.
attachments.contentType
string
必填
The detected MIME type of the file.
createdAt
string
Timestamp (UTC) when the campaign was created.
updatedAt
string
Timestamp (UTC) when the campaign was last updated.
代码示例
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/tcr-brands/{brandId}/campaigns' \
-H 'Authorization: AccessKey YOUR_ACCESS_KEY'CampaignRequest object
| Field | Type | Description | Mandatory |
|---|---|---|---|
| name | string | Name of your use case | Required |
| useCase | useCase | A use case that best matches the purpose of the campaign | Required |
| subUsecases | array<useCase> | If use case is MIXED or LOW_VOLUME mixed an array of 2-5 use cases | Optional. Unless useCase is LOW_VOLUME, MIXED |
| description | string | A detailed description of what the campaign is for | Required |
| embeddedLink | boolean | Whether messages will contain links. Provide at least one sample containing a link | Required |
| embeddedPhone | boolean | Whether messages will contain phone number. Provide at least one sample containing a phone number | Required |
| numberPool | boolean | Whether a campaign will be associated with more than 50 numbers e.g. customer service use case | Required |
| ageGated | boolean | Whether a campaign contains age-gated content based on carrier/ctia guidelines | Required |
| directLending | boolean | Whether a campaign includes content related to direct lending or loan arrangements | Required |
| subscriberOptin | boolean | Confirm customer opt in is collected and processed | Required |
| subscriberOptout | boolean | Confirm customer opt out is collected and processed | Required |
| subscriberHelp | boolean | Confirm an info message is returned if a customer sends “HELP” | Required |
| samples | array<string> | Between 1-5 sample messages. If directLending, embeddedPhone, embeddedLink is true provide relevant examples | Required. At least 1 sample |
| messageFlow | string | Provide details of how the customer will opt into this campaign. If you have a live web opt-in provide the URL and ensure the page has details on the T&Cs/data collection for opting in, and how to opt out | Required |
| helpKeywords | string | A comma separated list of keywords. Support of the word HELP is the minimum requirement for requesting help/info. | Required |
| optoutKeywords | string | A comma separated list of keywords. Support of the word STOP is the minimum requirement for OPT OUT. | Required |
| optInKeywords | string | A comma separated list of keywords. Support of the word START is the minimum requirement for OPT OUT. | Optional. Required if subscriberOptin is true |
| helpMessage | string | Help message of the campaign. A help message shall state the name of the service, contact (email or call centre), OPT IN and OPT OUT keywords. | Required |
| optinMessage | string | Provide an example of the message that will be sent after a customer has opted in. | Optional. Required if subscriberOptin is true |
| optoutMessage | sting | Provide an example of the message that will be sent after a customer has opted out. | Required |
| termsAndConditions | boolean | Indicates the campaign follows CTIA messaging principles and best practices | Required |
CampaignResponse object
| Field | Type | Description |
|---|---|---|
| useCase | useCase | A use case that best matches the purpose of the campaign |
| subUsecases | array<useCase> | If use case is MIXED or LOW_VOLUME mixed an array of 2-5 use cases |
| description | string | A detailed description of what the campaign is for |
| embeddedLink | boolean | Whether messages will contain links. Provide at least one sample containing a link |
| embeddedPhone | boolean | Whether messages will contain phone number. Provide at least one sample containing a phone number |
| numberPool | boolean | Whether a campaign will be associated with more than 50 numbers e.g. customer service use case |
| ageGated | boolean | Whether a campaign contains age-gated content based on carrier/ctia guidelines |
| directLending | boolean | Whether a campaign includes content related to direct lending or loan arrangements |
| subscriberOptin | boolean | Confirm customer opt in is collected and processed |
| subscriberOptout | boolean | Confirm customer opt out is collected and processed |
| subscriberHelp | boolean | Confirm an info message is returned if a customer sends “HELP” |
| samples | array<string> | Between 1-5 sample messages. If directLending, embeddedPhone, embeddedLink is true provide relevant examples |
| messageFlow | string | Provide details of how the customer will opt into this campaign. If you have a live web opt-in provide the URL and ensure the page has details on the T&Cs/data collection for opting in, and how to opt out |
| helpKeywords | string | A comma separated list of keywords. Support of the word HELP is the minimum requirement for requesting help/info. |
| optoutKeywords | string | A comma separated list of keywords. Support of the word STOP is the minimum requirement for OPT OUT. |
| optInKeywords | string | A comma separated list of keywords. Support of the word START is the minimum requirement for OPT OUT. |
| helpMessage | string | Help message of the campaign. A help message shall state the name of the service, contact (email or call centre), OPT IN and OPT OUT keywords. |
| optinMessage | string | <p> </p> |
| optoutMessage | sting | Provide an example of the message that will be sent after a customer has opted in. |
| termsAndConditions | boolean | Indicates the campaign follows CTIA messaging principles and best practices |
| brandId | string | Alphanumeric identifier of the brand associated with this campaign. The specified brand MUST be APPROVED. |
| campaignId | string | Alphanumeric identifier of the campaign |
| campaignStatus | campaignStatus | Campaign status |