Send an invitation

POST/v1/invitations

Sends a templated invitation to a phone number: the one way to start a conversation with a customer who has not messaged you first.

Requirements

Idempotency-Key header: required. This is business-initiated contact, and a blind retry must never send two.

Behavior

Refusals are checked in a fixed order, most actionable first: validation, then idempotency, then template authorization, then backlog admission, then chat state, then consent.
HTTP 429 code 1002 is admission control on your backlog, not a rate limit: your queued-but-unsent invitations plus this one would take longer to deliver than the delivery horizon allows, so the request is refused rather than queued: an invitation delivered hours late could go out against consent revoked in the meantime. Retry-After reflects when your backlog will actually clear and can legitimately be hours; retrying sooner is refused again. Nothing is queued and no key is recorded, so the same key succeeds on retry.
A backlog refusal is checked before the chat-state and consent gates (validation still runs first): a recipient who has also opted out still fails with the consent error once there is room.

Errors

HTTP 403: invitation_card_not_granted (your brand is no longer approved for the card shape the template renders), consent_required
HTTP 409: idempotency_key_reused, idempotency_key_processing, chat_superseded, chat_closed
HTTP 422: field-level validation; unknown_template; field_removed if the request still carries the retired parameters or brand_logo_att_id fields
HTTP 429: backlog_horizon_exceeded, with Retry-After

Header ParametersExpand Collapse

"Idempotency-Key": string

Body ParametersJSONExpand Collapse

reference_id: string

REQUIRED correlation handle: an order number, case id or similar. Apple bounds its length and does not allow quotes. Echoed on the delivery webhooks.

template_id: string

One of YOUR invitation template ids (invt_…, from POST /v1/invitation_templates): the card’s name and logo come from the template, and the platform picks the right card from whether it carries a logo. Unknown returns HTTP 422 code 1081.

to: string

The customer’s phone number, bare E.164 (partner formatting tolerated); malformed returns HTTP 422 code 1071.

locale: optional string

Optional locale for the card rendering.

ReturnsExpand Collapse

id: string

Invitation id (inv_…).

chat_id: string

The tel-handled chat carrying the invitation delivery; NOT addressable for organic sends.

delivery: "queued"

message_id: string

The invitation delivery’s message id; poll it via GET /v1/messages/{msg}.

to: string

The canonical tel:+E164 handle form of the request’s to.

Send an invitation

curl https://messages.api.linqapp.com/v1/invitations \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $LINQ_AMB_API_KEY" \
    -d '{
          "reference_id": "ride-88214",
          "template_id": "invt_a4f2c718d0",
          "to": "+15555550142"
        }'

{
  "id": "inv_6b2e04",
  "chat_id": "chat_4f81b2",
  "message_id": "msg_2c7d90",
  "to": "tel:+15555550142",
  "delivery": "queued"
}

Returns Examples

{
  "id": "inv_6b2e04",
  "chat_id": "chat_4f81b2",
  "message_id": "msg_2c7d90",
  "to": "tel:+15555550142",
  "delivery": "queued"
}