Alphanumeric Senders

Overview

Alphanumeric originators are combinations of letters (alphabets) and numbers (digits) for sending SMS messages to mobile phones. Alphanumerics work one way and are the most common form of originator worldwide except for the USA and Canada.

Alphanumeric originators do not have a country of origin and have to be registered in destination countries individually. Some countries may require additional registration processes to ensure the alphanumeric sender ID meets local compliance requirements.

Originator Restrictions

If you use a company or brand name as the originator, the number of characters needs to be between 3 and 11.

API Access

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

List Alphanumeric Senders

In order to retrieve all alpha numbers available in your workspace you can use this request.

GET

/workspaces/{workspaceId}/numbers-alpha

List alpha numbers for the given workspace. This endpoint supports pagination. To learn more about pagination, refer to API Access Common Usage Page.

Parameter query

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.

Payload respons

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. To know more, refer to the pagination section.

results

array of object

wajib

Tampilkan atribut turunan

results.id

string

wajib

The unique identifier of the alpha number.

results.endpointId

string

wajib

The unique identifier of the endpoint that the alpha number is associated with.

results.alphaString

string

wajib

The alpha string of the alpha number. This is usually the phone number in string format following the international format.

results.createdAt

string

wajib

results.updatedAt

string

wajib

results.order

object

An alpha number order. It contains the country codes for which the alpha number is ordered, the order status and more.

Tampilkan atribut turunan

results.order.countryCodes

array of string

wajib

results.order.status

string

The status of an alpha number order.

Possible values: draft, submitted, processing, fulfilled, rejected, cancelled

results.order.createdAt

string

wajib

results.order.updatedAt

string

wajib

results.endpoint

object

wajib

A representation of an endpoint. It contains details such as the capabilities, dependencies, and more.

Tampilkan atribut turunan

results.endpoint.id

string

wajib

The ID of the endpoint.

results.endpoint.type

string

wajib

The type of the endpoint. It can be a long code number, short code number, alpha number, ip pool, or rcs google agent.

Possible values: long-code-number, short-code-number, alpha-number, ip-pool, rcs-google-agent

results.endpoint.instanceId

string

wajib

The unique identifier of the instance.

results.endpoint.name

string

wajib

The name of the endpoint. For some cases it will be the number in international format as string.

results.endpoint.capabilities

array of object

wajib

Tampilkan atribut turunan

results.endpoint.capabilities.name

string

wajib

Possible values: sms

results.endpoint.capabilities.inbound

object

Tampilkan atribut turunan

results.endpoint.capabilities.inbound.status

string

wajib

Possible values: active, inactive, available, unavailable

results.endpoint.capabilities.inbound.issues

array of string

results.endpoint.capabilities.outbound

object

Tampilkan atribut turunan

results.endpoint.capabilities.outbound.status

string

wajib

Possible values: active, inactive, available, unavailable

results.endpoint.capabilities.outbound.destinationStatuses

object

Tampilkan atribut turunan

results.endpoint.capabilities.outbound.destinationStatuses.active

number

results.endpoint.capabilities.outbound.destinationStatuses.inactive

number

results.endpoint.capabilities.outbound.destinationStatuses.available

number

results.endpoint.capabilities.outbound.destinationStatuses.unavailable

number

results.endpoint.capabilities.outbound.supportsDestinations

boolean

Whether the number supports destinations

results.endpoint.capabilities.outbound.issues

array of string

results.endpoint.dependencies

array of object

The dependencies of the endpoint. It shows the connectors that the endpoint is connected to.

Tampilkan atribut turunan

results.endpoint.dependencies.type

string

Possible values: connector

results.endpoint.dependencies.connectorId

string

wajib

results.endpoint.dependencies.connectorTemplateRef

string

wajib

results.endpoint.dependencies.capabilities

array of string

results.endpoint.issues

array of string

results.endpoint.provisioningStatus

string

wajib

Possible values: provisioned, provisioning, deprovisioned, deprovisioning

results.endpoint.whatsApp

object

WhatsApp pre-verification details for this endpoint, if applicable. Only present for long code numbers from WhatsApp-capable providers.

Tampilkan atribut turunan

results.endpoint.whatsApp.whatsAppId

string

results.endpoint.whatsApp.status

string

WhatsApp number status

Possible values: unknown, already-exists, installed, verified, not-verified, expired

results.endpoint.whatsApp.stage

string

results.endpoint.whatsApp.attempt

integer

results.endpoint.whatsApp.nextAttemptAt

string

results.endpoint.whatsApp.verificationExpiresAt

string

results.endpoint.whatsApp.requestedCodeAt

string

results.endpoint.whatsApp.createdAt

string

results.endpoint.whatsApp.updatedAt

string

results.endpoint.createdAt

string

wajib

results.endpoint.updatedAt

string

wajib

Contoh kode

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

Contoh kode

curl "https://api.bird.com/workspaces/{workpaceId}/numbers-alpha/" \
     -H 'Authorization: AccessKey <your-access-key>'

Contoh kode

{
    "results": [
        {
            "id": "uuid",
            "alphaString": "string",
            "endpointId": "uuid",
            "createdAt": "2023-10-20T11:49:47.436-03:00",
            "updatedAt": "2023-10-20T11:49:47.479-03:00",
            "endpoint": {
                "id": "uuid",
                "type": "alpha-number",
                "instanceId": "uuid",
                "name": "string",
                "createdAt": "2023-10-20T11:49:47.436-03:00",
                "updatedAt": "2023-10-20T11:49:47.436-03:00",
                "capabilities": [
                    {
                        "name": "sms",
                        "inbound": null,
                        "outbound": {
                            "status": "active"
                        }
                    }
                ]
            }
        },
        {
            "id": "uuid",
            "alphaString": "string",
            "endpointId": "uuid",
            "createdAt": "2023-10-20T11:49:47.392-03:00",
            "updatedAt": "2023-10-20T11:49:47.392-03:00",
            "endpoint": {
                "id": "uuid",
                "type": "alpha-number",
                "instanceId": "uuid",
                "name": "string",
                "createdAt": "2023-10-20T11:49:47.392-03:00",
                "updatedAt": "2023-10-20T11:49:47.392-03:00",
                "capabilities": [
                    {
                        "name": "sms",
                        "inbound": null,
                        "outbound": {
                            "status": "active"
                        }
                    }
                ]
            }
        }
    ]
}

Get an Alphanumeric Sender

In order to retrieve an alpha number available in your workspace you can use this request.

GET

/workspaces/{workspaceId}/numbers-alpha/{alphaNumberId}

Get a specific alpha number for a given workspace by id.

Payload respons

string

wajib

The unique identifier of the alpha number.

endpointId

string

wajib

The unique identifier of the endpoint that the alpha number is associated with.

alphaString

string

wajib

The alpha string of the alpha number. This is usually the phone number in string format following the international format.

createdAt

string

wajib

updatedAt

string

wajib

order

object

An alpha number order. It contains the country codes for which the alpha number is ordered, the order status and more.

Tampilkan atribut turunan

order.countryCodes

array of string

wajib

order.status

string

The status of an alpha number order.

Possible values: draft, submitted, processing, fulfilled, rejected, cancelled

order.createdAt

string

wajib

order.updatedAt

string

wajib

endpoint

object

wajib

A representation of an endpoint. It contains details such as the capabilities, dependencies, and more.

Tampilkan atribut turunan

endpoint.id

string

wajib

The ID of the endpoint.

endpoint.type

string

wajib

The type of the endpoint. It can be a long code number, short code number, alpha number, ip pool, or rcs google agent.

Possible values: long-code-number, short-code-number, alpha-number, ip-pool, rcs-google-agent

endpoint.instanceId

string

wajib

The unique identifier of the instance.

endpoint.name

string

wajib

The name of the endpoint. For some cases it will be the number in international format as string.

endpoint.capabilities

array of object

wajib

Tampilkan atribut turunan

endpoint.capabilities.name

string

wajib

Possible values: sms

endpoint.capabilities.inbound

object

Tampilkan atribut turunan

endpoint.capabilities.inbound.status

string

wajib

Possible values: active, inactive, available, unavailable

endpoint.capabilities.inbound.issues

array of string

endpoint.capabilities.outbound

object

Tampilkan atribut turunan

endpoint.capabilities.outbound.status

string

wajib

Possible values: active, inactive, available, unavailable

endpoint.capabilities.outbound.destinationStatuses

object

Tampilkan atribut turunan

endpoint.capabilities.outbound.destinationStatuses.active

number

endpoint.capabilities.outbound.destinationStatuses.inactive

number

endpoint.capabilities.outbound.destinationStatuses.available

number

endpoint.capabilities.outbound.destinationStatuses.unavailable

number

endpoint.capabilities.outbound.supportsDestinations

boolean

Whether the number supports destinations

endpoint.capabilities.outbound.issues

array of string

endpoint.dependencies

array of object

The dependencies of the endpoint. It shows the connectors that the endpoint is connected to.

Tampilkan atribut turunan

endpoint.dependencies.type

string

Possible values: connector

endpoint.dependencies.connectorId

string

wajib

endpoint.dependencies.connectorTemplateRef

string

wajib

endpoint.dependencies.capabilities

array of string

endpoint.issues

array of string

endpoint.provisioningStatus

string

wajib

Possible values: provisioned, provisioning, deprovisioned, deprovisioning

endpoint.whatsApp

object

WhatsApp pre-verification details for this endpoint, if applicable. Only present for long code numbers from WhatsApp-capable providers.

Tampilkan atribut turunan

endpoint.whatsApp.whatsAppId

string

endpoint.whatsApp.status

string

WhatsApp number status

Possible values: unknown, already-exists, installed, verified, not-verified, expired

endpoint.whatsApp.stage

string

endpoint.whatsApp.attempt

integer

endpoint.whatsApp.nextAttemptAt

string

endpoint.whatsApp.verificationExpiresAt

string

endpoint.whatsApp.requestedCodeAt

string

endpoint.whatsApp.createdAt

string

endpoint.whatsApp.updatedAt

string

endpoint.createdAt

string

wajib

endpoint.updatedAt

string

wajib

Contoh kode

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

Contoh kode

curl "https://api.bird.com/workspaces/{workpaceId}/numbers-alpha/{alphaNumberID}" \
     -H 'Authorization: AccessKey <your-access-key>'

Contoh kode

{
    "id": "uuid",
    "alphaString": "string",
    "endpointId": "uuid",
    "createdAt": "2023-10-20T11:49:47.436-03:00",
    "updatedAt": "2023-10-20T11:49:47.479-03:00",
    "endpoint": {
        "id": "uuid",
        "type": "alpha-number",
        "instanceId": "uuid",
        "name": "string",
        "createdAt": "2023-10-20T11:49:47.436-03:00",
        "updatedAt": "2023-10-20T11:49:47.436-03:00",
        "capabilities": [
            {
                "name": "sms",
                "inbound": null,
                "outbound": {
                    "status": "active"
                }
            }
        ]
    }
}

Add country destination to an Alphanumeric Sender

POST

/workspaces/{workspaceId}/endpoints/{endpointId}/destinations/activate

Activate Workspace Endpoint Destinations

Parameter path

workspaceId

string

The unique identifier of the workspace.

Parameter query

validate

boolean

When set, only validates the request payload without mutating any data.

Payload permintaan

capability

string

wajib

Possible values: voice, sms, mms, whatsapp, email, rcs-google

countryCodes

array of string

wajib

Payload respons

subscriptionPrices

object

error

object

A validation error returned from the API. The details map keys are JSON paths pointing into the request body / parameters; values are arrays of human-readable messages describing each problem with that path.

Tampilkan atribut turunan

error.code

string

wajib

A unique code that identifies the error. This code can be used to programmatically identify the error.

error.details

object

Per-field validation messages keyed by JSON path.

error.message

string

wajib

A human-readable message that describes the error.

Contoh kode

curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/endpoints/{endpointId}/destinations/activate' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

Cancel country destination from an Alphanumeric Sender

POST

/workspaces/{workspaceId}/endpoints/{endpointId}/subscriptions/{subscriptionName}/cancel

Use this endpoint to deactivate a subscription. That will stop charges and messages from being sent.

Payload respons

name

string

wajib

The name of the subscription. For long codes, this value will be main. For alpha and short code numbers, this value will be the destination country code.

status

string

wajib

The status of the endpoint subscription. It can be active or inactive.

Possible values: active, inactive

price

object

Money combines an amount of money with its currency.

Tampilkan atribut turunan

price.currencyCode

string

wajib

Currency as ISO 4217 code (three digits). An example would be EUR for Euro.

Possible values: EUR, USD, GBP, AUD, SGD, IDR, INR, MXN

price.amount

integer

wajib

price.exponent

integer

wajib

Usually a negative number to specify the exponent for decimal precision. e.g., 1540 * (10^-2) = 15.4

subscription

object

Tampilkan atribut turunan

subscription.id

string

wajib

The subscription unique identifier.

subscription.correlationId

string

wajib

The correlation links the subscription to its number. Hence, the correlationId is the numberId.

subscription.status

string

wajib

The status of the accounting subscription. It can be none, active, canceling, canceled, or planned.

Possible values: none, active, inactive, canceling, canceled, planned

subscription.subscribedAt

string

The date and time when the subscription was created.

subscription.updatedAt

string

subscription.canceledAt

string

The date and time when the subscription was canceled.

subscription.startAt

string

The date and time when the subscription should start.

subscription.endAt

string

The date and time when the subscription should end.

Contoh kode

curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/endpoints/{endpointId}/subscriptions/{subscriptionName}/cancel' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

Remove country destination from an Alphanumeric Sender

POST

/workspaces/{workspaceId}/endpoints/{endpointId}/destinations/deactivate

Deactivate Workspace Endpoint Destinations

Payload permintaan

capability

string

wajib

Possible values: voice, sms, mms, whatsapp, email, rcs-google

countryCodes

array of string

wajib

Payload respons

results

array of object

wajib

Tampilkan atribut turunan

results.name

string

wajib

results.countryCode

string

wajib

The country code in ISO 3166-1 alpha-2 format.

results.immutable

boolean

results.capabilities

array of object

Tampilkan atribut turunan

results.capabilities.name

string

wajib

Possible values: voice, sms, mms, whatsapp, email, rcs-google

results.capabilities.status

string

wajib

Possible values: active, inactive, available, unavailable

results.capabilities.issues

array of string

results.isBlockedForCapability

object

Indicates whether specific capabilities are blocked for a given number.

Tampilkan atribut turunan

results.isBlockedForCapability.voice

boolean

results.isBlockedForCapability.sms

boolean

results.isBlockedForCapability.mms

boolean

results.isBlockedForCapability.whatsapp

boolean

results.isBlockedForCapability.email

boolean

results.isBlockedForCapability.rcs-google

boolean

Contoh kode

curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/endpoints/{endpointId}/destinations/deactivate' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'