Allo

Declare sender ID

Declares an alphanumeric sender ID on one of your accounts, so the account can send SMS under that name. The sender ID is created with status PENDING and…

POST/v2/api/partner/accounts/{account_id}/sender_ids

Declares an alphanumeric sender ID on one of your accounts, so the account can send SMS under its brand name instead of a phone number. In France, automated SMS cannot be sent from mobile numbers, so a sender ID is how your software texts the account's customers. The response returns the sender ID with status PENDING.

Request

  • sender_id is required: 1 to 11 letters or digits, with no spaces or symbols, for example PLOMBMARTIN. A missing value fails with MISSING_FIELD, any other format with SENDER_ID_INVALID_FORMAT. The name has to represent the account's actual business, see the Sender ID naming rules.
  • example_content is optional: an example of a message the account will send, up to 1,000 characters. Allo's reviewer reads it. A longer value fails with EXAMPLE_CONTENT_TOO_LONG.

Rules

  • A sender ID belongs to one Allo account only. A name already held by another Allo account fails with 409 SENDER_ID_ALREADY_EXISTS.
  • An account holds at most 3 sender IDs. A fourth fails with 409 MAX_SENDER_IDS_REACHED.
  • Sending the same sender_id again for the same account returns the existing sender ID, so a retry is safe.
  • You can only declare sender IDs on accounts your own API key created. Any other account returns 404 PARTNER_ACCOUNT_NOT_FOUND.

Review

Allo reviews every sender ID by hand, usually in 1 to 5 business days. When the review ends, Allo sends partner.sender_id.validated or partner.sender_id.failed to your own webhook endpoint. Without a webhook endpoint, poll Get sender ID.

Once the sender ID is VALIDATED, the account sends SMS with it through Send SMS (France).

Authorization

Authorizationstring · headerrequired

Api-Key ak_live_…

Path parameters

account_idstringrequired

The account id returned by Create account (usr-*).

Body

sender_idstringrequired

1 to 11 letters or digits, with no spaces or symbols. It must not belong to another Allo account.

example_contentstring | null

Optional. An example of a message the account will send, shown to the Allo reviewer.

Responses

201Sender ID declared, waiting for Allo's review
dataobject

An alphanumeric sender ID declared on an account you provisioned.

7 fields
idstring

The sender ID's id (vsi-*).

account_idstring

The account the sender ID is declared on.

partner_client_refstring | null

Your own reference, set when the account was created.

sender_idstring

The name recipients see instead of a phone number.

statusenum<string>

PENDING: waiting for Allo's review. VALIDATED: approved, the account can send SMS with it. FAILED: rejected, declare another name. DISABLED: deactivated by Allo after validation, sending with it is refused.

PENDINGVALIDATEDFAILEDDISABLED

example_contentstring | null

The example message sent with the declaration.

created_atstring<date-time>

When the sender ID was declared.

400Validation error: MISSING_FIELD (sender_id), SENDER_ID_INVALID_FORMAT (sender_id is not 1 to 11 letters or digits) or EXAMPLE_CONTENT_TOO_LONG (example_content is longer than 1000 characters).
errorobject
401
403The API key lacks the PARTNER scope.
errorobject
404No account with this id was provisioned by your API key, or the account is deactivated (PARTNER_ACCOUNT_NOT_FOUND).
errorobject
409The sender ID already belongs to another Allo account (SENDER_ID_ALREADY_EXISTS), or the account already has 3 sender IDs (MAX_SENDER_IDS_REACHED).
errorobject
429