Communication API

Use the Chazt Communication API to send an approved message, notification, or call through a business's own configured Chazt workspace and to receive verifiable status updates.

Base URL and authentication

Production base URL:

https://api.chazt.com

Interactive schema: Chazt Communication API Swagger

Server-to-server requests use an organization API key:

Authorization: Api_Key <your-key>
Content-Type: application/json

Create the key as a workspace owner in Developer Tools. The secret is shown only once and must be stored securely on your server. The workspace and integration identity are derived from the key; do not send a workspace identifier in request bodies.

Endpoints

POST /v2/communications/{operationId}/acknowledge is for an authenticated Chazt user who is the intended recipient. An organization API key cannot acknowledge its own communication.

Check capabilities first

curl --request GET \
  --url https://api.chazt.com/v2/communications/capabilities \
  --header "Authorization: Api_Key $CHAZT_API_KEY"

The response reports readiness separately for WhatsApp messages, WhatsApp calls, ordinary phone calls, Chazt notifications, paired wearable delivery, and direct Meta glasses delivery. Submit an operation only when the selected channel reports ready: true.

Capabilities describe the current workspace configuration. They do not override customer consent, contact hours, approved templates, calling eligibility, or channel policy.

Submit a communication

Every submission requires a unique x-idempotency-key. Repeating the same request with the same key returns the original safe response. Reusing the key with different content returns HTTP 409.

curl --request POST \
  --url https://api.chazt.com/v2/communications \
  --header "Authorization: Api_Key $CHAZT_API_KEY" \
  --header "Content-Type: application/json" \
  --header "x-idempotency-key: order-1042-status-v1" \
  --data '{
    "externalOperationId": "order-1042-status-v1",
    "action": "message",
    "channel": "whatsapp_message",
    "recipientRef": "+15551234567",
    "recipientType": "e164",
    "message": "Your order is ready for collection.",
    "urgency": "normal",
    "deliverySurface": "phone",
    "requiresAcknowledgement": false,
    "metadata": {
      "orderReference": "1042"
    }
  }'

Use a new idempotency key and externalOperationId for each intended communication. Both are isolated to the authenticated workspace and integration client.

Request values

Use action: call only with whatsapp_call or phone_call. Call channels require action: call.

Sensitive or high-risk content may be replaced with a generic notification that directs the recipient to the authenticated Chazt application. Wearable previews are intentionally limited.

Read operation status

The create, status, and cancellation endpoints return a safe operation view:

{
  "operationId": "f5126de1-8d71-44c3-a7bb-405e2edc1828",
  "externalOperationId": "order-1042-status-v1",
  "channel": "whatsapp_message",
  "status": "delivered",
  "createdAt": "2026-09-05T10:00:00.000Z",
  "updatedAt": "2026-09-05T10:00:03.000Z",
  "acknowledgementState": "not_required",
  "deliveryEvidenceRef": "whatsapp:<provider-reference>",
  "errorCode": null
}

Possible statuses are accepted, queued, sending, ringing, connected, delivered, acknowledged, completed, failed, expired, cancelled, and requires_user_session.

Terminal results and provider-confirmed evidence should be saved against the originating business action. An accepted request is not proof of delivery.

Safe failure codes can include:

• customer_window_expired
• recipient_not_allowed
• provider_rate_limited
• channel_authentication_failed
• provider_request_invalid
• recipient_not_found
• channel_not_configured
• recipient_permission_required
• expired
• provider_delivery_failed

Signed status webhooks

Register one HTTPS callback for each integration client:

curl --request POST \
  --url https://api.chazt.com/v2/communications/webhooks \
  --header "Authorization: Api_Key $CHAZT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"callbackUrl":"https://example.com/webhooks/chazt"}'

The signing secret is returned only when the webhook is registered or replaced. Store it securely. Chazt sends:

• x-chazt-event-id
• x-chazt-timestamp
• x-chazt-signature: sha256=<hex-hmac>

Verify the signature against the exact UTF-8 request body before parsing it, and deduplicate deliveries using x-chazt-event-id. Return a 2xx response only after the event has been safely accepted. Chazt retries failed deliveries with bounded backoff.

Webhook events include communication.accepted, communication.ringing, communication.connected, communication.delivered, communication.acknowledged, communication.completed, communication.failed, communication.expired, and communication.cancelled.

Current channel limitations

• WhatsApp messaging is available only when the workspace's WhatsApp connection is complete and the recipient and conversation satisfy WhatsApp requirements.
• Ordinary phone calling is available only when the workspace has an active calling account.
• Chazt notifications require notification delivery to be configured.
• Paired wearable delivery uses a ready Chazt notification, WhatsApp, or calling route.
• Outbound WhatsApp calls can return requires_user_session until the required user session is available.
• Direct Meta glasses delivery is not currently available. A paired device may receive a supported phone or Chazt notification through its normal device behavior.

Do not claim that a message, call, or wearable notification completed until the operation status and delivery evidence confirm it.