SMS Use Cases

Overview

To programmatically install an SMS channel, the API expects a reference to a use case in the request. For US 10DLC and North American Toll-Free Numbers, the use case entity is created when registering for these types of numbers. For other types of senders, like international phone numbers or alphanumeric senders, you need to create a generic use case. Use cases can be reused for multiple channels (for different senders) when the use case of the channels is the same.

List Use Cases

GET

/workspaces/{workspaceId}/use-cases

List use cases for a workspace

查询参数

limit

integer

Limits the number of results to return.

pageToken

string

The cursor that keeps track of the current position in the results.

reverse

boolean

Reverses the order in which the results are returned.

响应载荷

results

array of object

显示子属性

results.id

string

必填

results.name

string

必填

results.status

string

Possible values: created, cancelled, error, deleted, declined, approved

results.use

string

必填

results.caseType

string

必填

Possible values: default, tendlc, tfn-verification

results.definitionVersion

string

results.description

string

必填

results.additionalFields

object

results.integrationState

object

显示子属性

results.integrationState.externalId

string

results.integrationState.status

string

results.integrationState.updatedAt

string

results.integrationState.additionalFields

object

results.tags

array of object

显示子属性

results.tags.key

string

results.tags.value

string

results.createdAt

string

必填

results.updatedAt

string

nextPageToken

string

The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display.

代码示例

curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/use-cases' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

Get a Use Case

GET

/workspaces/{workspaceId}/use-cases/{useCaseId}

Get workspace use case

响应载荷

string

必填

name

string

必填

status

string

Possible values: created, cancelled, error, deleted, declined, approved

use

string

必填

caseType

string

必填

Possible values: default, tendlc, tfn-verification

definitionVersion

string

description

string

必填

additionalFields

object

integrationState

object

显示子属性

integrationState.externalId

string

integrationState.status

string

integrationState.updatedAt

string

integrationState.additionalFields

object

Create a Use Case

POST

/workspaces/{workspaceId}/use-cases

Creates a new use case for a workspace

请求载荷

name

string

必填

use

string

必填

caseType

string

必填

Possible values: default, tendlc, tfn-verification

definitionVersion

string

description

string

必填

additionalFields

object

响应载荷

string

必填

name

string

必填

status

string

Possible values: created, cancelled, error, deleted, declined, approved

use

string

必填

caseType

string

必填

Possible values: default, tendlc, tfn-verification

definitionVersion

string

description

string

必填

additionalFields

object

integrationState

object

显示子属性

integrationState.externalId

string

integrationState.status

string

integrationState.updatedAt

string

integrationState.additionalFields

object

Example request

代码示例

curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/use-cases' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>' \
--data '{
    "name": "Multi-factor authentication",
    "description": "MFA messages via SMS",
    "use": "2FA",
    "caseType": "default",
    "additionalFields": {
        "sample_messages": [
            "Your login code is 123456."
        ]
    }
}'

Property	Type	Required	Description
name	string	Yes	The name of your use case, e.g. My transactional use case.
use	string	Yes	Type of use case. Choose one of the following: 2FA, ACCOUNT_NOTIFICATION, CUSTOMER_CARE, DELIVERY_NOTIFICATION, FRAUD_ALERT, HIGHER_EDUCATION, MARKETING, POLLING_VOTING, PUBLIC_SERVICE_ANNOUNCEMENT, SECURITY_ALERT
caseType	string	Yes	Type of use case. Use always default for non-10DLC or TFN use cases.
description	string	Yes	Description of your use case.
additionalFields.sample_messages	array of strings	Yes	Message samples (minimal 1), for the use case. Can be used to request content approval at carriers.

The ID returned in the request result can be used as useCaseId value when linking the use case to the number, and in the request to create an SMS channel.