amb-routing-rules

Create an Apple Messages for Business routing rule

Creates a routing rule for one of your Apple Messages for Business brands. Set is_default to make it the rule that catches a conversation matching nothing else. A business can have only one default rule, and creating a second while one exists returns a 409.

post/v1/amb/routing-rules

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/amb/routing-rules
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Request body

business_account_idstring required
match_kind'both' required

What a routing rule matches against the entry point that started the conversation.

  • intent matches on the entry point's intent alone: match_intent_id is set and match_group_id is null.
  • group matches on the entry point's group alone: match_group_id is set and match_intent_id is null.
  • both matches only when the entry point carries the given intent and the given group together, so match_intent_id and match_group_id are both set. There are two match fields rather than one because both needs to carry an intent and a group at once.
match_intent_idstring nullable required

The entry point intent to match, as sent in Apple's intentID. Required when match_kind is intent or both, and rejected when it is group.

match_group_idstring nullable required

The entry point group to match, as sent in Apple's groupID. Required when match_kind is group or both, and rejected when it is intent.

queuestring required

Queue label used for routing and filtering conversations.

precedenceinteger

Evaluation order among this business's rules. The highest-precedence rule a conversation matches wins. Omit it to default to 0.

is_defaultboolean

Set to make this the rule that catches a conversation matching nothing else. A business can have only one; creating a second while one exists returns a 409.

Example request

{
  "business_account_id": "abz_01krdgeqcxet5s7t44vh8rt9mg",
  "match_kind": "intent",
  "match_intent_id": "order_status",
  "match_group_id": "support",
  "precedence": 10
}

Response

Routing rule created.

created_atstring date-time required
updated_atstring date-time required
idstring required
business_account_idstring required
match_kind'intent' | 'group' | 'both' required

What a routing rule matches against the entry point that started the conversation.

  • intent matches on the entry point's intent alone: match_intent_id is set and match_group_id is null.
  • group matches on the entry point's group alone: match_group_id is set and match_intent_id is null.
  • both matches only when the entry point carries the given intent and the given group together, so match_intent_id and match_group_id are both set. There are two match fields rather than one because both needs to carry an intent and a group at once.
match_intent_idstring nullable

The entry point intent this rule matches, as sent in Apple's intentID. Set when match_kind is intent or both, null when it is group.

match_group_idstring nullable

The entry point group this rule matches, as sent in Apple's groupID. Set when match_kind is group or both, null when it is intent.

queuestring required

The queue a matching conversation is filed into. A queue is a label your console filters by rather than a resource you create ahead of time, so any value routes.

precedenceinteger required

Evaluation order among this business's rules. The highest-precedence rule a conversation matches wins; rules tied on precedence are evaluated by their id.

is_defaultboolean required

Whether this rule catches a conversation that matches nothing else. A business has at most one. A conversation created or reopened while none exists routes to an empty queue, which the console lists as unrouted.

Example response

{
  "created_at": "2026-05-20T09:14:52Z",
  "updated_at": "2026-05-25T16:42:01Z",
  "id": "arr_01krdgeqcxet5s7t44vh8rt9mg",
  "business_account_id": "abz_01krdgeqcxet5s7t44vh8rt9mg",
  "match_kind": "intent",
  "match_intent_id": "order_status",
  "match_group_id": "support",
  "queue": "billing",
  "precedence": 10
}

Changes

No recorded changes to this operation across all 2 revisions of this API.