One connection per business
Create an account and system connection per business. Keep its one-time token on the server; rotation invalidates the old token.
Connect your system through Awam’s shared number or the business’s own Meta-connected number. Every business has its own connection, token, billing and workflow.
Create an account and system connection per business. Keep its one-time token on the server; rotation invalidates the old token.
Awam mode uses Awam templates. Own-number coexistence needs the owner’s Meta authorization and that account’s approved templates.
Entering a configured stage triggers its approved template. Poll outcomes and replies through the API.
Create an Awam workspace per business. Choose Awam’s number or connect its own number in Settings → WhatsApp.
In Settings → Connect your system, create an API connection, select its workflow and store the one-time token on your server. Use its Event API URL for this guide’s JSON; the raw Webhook URL accepts third-party systems’ own field names.
Configure the stage’s approved template and variable mappings. Send one sample; it only captures fields and does not send. Map the sample event value to a stage in the connection screen, then send a second event with a new event_id.
Check the account API before launch, then monitor messages and replies. Active plan quota pays first; paid wallet covers overage. Trial credit is limited and expires.
Use a unique stable event_id for each change. Retrying the same event is safe. Map its event value to a stage first; include service or appointment data if the template needs it.
event external status mapped to an Awam stageobject.id your stable order ID; shown in the tracking variable when the template maps to itobject.customer name, international phone and opt-inobject.scheduled_at send an explicit timezone such as Z or +03:00; Awam displays it in the saved business timezoneAPI appointment times must include Z or a numeric offset. Awam stores UTC and displays appointments and reminders in the business timezone. A local time without an offset can appear at the wrong hour or day.
Awam's internal order ID stays unchanged. event_id is for duplicate protection and differs from object.id; do not use event_id as the order ID.
curl -X POST "https://awam.io/api/v1/events/YOUR_CONNECTION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"event_id": "workspace-42-record-100-update",
"event": "workflow.status_changed",
"object": {
"id": "CLIENT-ORDER-100",
"type": "request",
"customer": {"name": "Mariam", "phone": "+201001112222", "language": "ar", "consent": true},
"details": "General consultation",
"scheduled_at": "2026-10-08T09:30:00.000Z"
}
}'The API token is hashed and bound to one workspace. Never put it in browser or mobile code, logs, repositories or AI chats. The request cannot select an arbitrary sender or template; the connection and stage configuration control those.
/api/v1/events/{token}Send the sample JSON with a stable unique event_id per change. The first event may only be a sample; 202 is not delivery.
/api/v1/account/{token}Workspace/sender health, sender-specific approved templates, balances in minor units, quota and otp.available.
/api/v1/messages/{token}?limit=30&before_id=...Stage-message results for this connection only, newest first. Read status and error; page with next_before_id.
/api/v1/responses/{token}?after_id=0Button replies only for this connection’s records. Persist next_after_id for the next poll.
/api/v1/otp/{token}Awam generates and sends OTP; GET reports message status only. Available after activation on the Awam sender.
/api/v1/otp/{token}/verifyVerify the entered code. verified:true is returned once; verification does not charge another message.
/connect/whatsapp#{connect-token}Separate own-number Meta connect link. Open it in a browser; never use it as the API token.
In Settings → Connect your system, open the API connection and enable verification codes. The workspace owner enables it directly; there is no Awam admin approval. It requires Meta’s approved awam_verification_code Authentication template and Awam’s number. Tell recipients the code comes from Awam. Awam generates and verifies it; your server grants access only after verified:true.
POST /api/v1/otp/{token} send unique request_id, international phone, purpose such as signup or login, and consent:true; omit code so Awam generates itGET /api/v1/otp/{token}?request_id=… poll message delivery only; this does not verify the codePOST /api/v1/otp/{token}/verify From your server submit request_id, phone, purpose and the entered code. Only verified:true permits your action, once.curl -X POST "https://awam.io/api/v1/otp/YOUR_CONNECTION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"request_id":"signup_72658432","phone":"+201001112222","purpose":"signup","consent":true}'
# Replace 482916 with the code the person entered; call from your SERVER:
curl -X POST "https://awam.io/api/v1/otp/YOUR_CONNECTION_TOKEN/verify" \
-H "Content-Type: application/json" \
-d '{"request_id":"signup_72658432","phone":"+201001112222","purpose":"signup","code":"482916"}'Show connection health and balance inside your own UI. When status is not connected, show Connect WhatsApp. When reauthorization_required is true, show Reconnect. When balance is low, show Top up or contact the account administrator.
available_balance_minor / 100messages_remainingoverage_price_minor / 100whatsapp.statusStatuses include pending, sent, delivered, read, failed, waiting_template and blocked_balance. sent means Meta accepted the request, not delivered. blocked_balance means eligible quota or funding is unavailable.
sampleReceived: true means the first event only captured a sample. Map its event to a stage, then send a new event_id.
needsMapping: true means the external event has no stage mapping. Add that status in the connection screen; eligible waiting events can be replayed.
waiting_template means the stage template is unavailable. On Awam’s number choose an enabled approved platform template; on a coexistence number refresh that business’s Meta templates and choose an approved one. Supply required service and appointment values.
blocked_balance means eligible quota and funds are insufficient. Inspect billing in the account API. sent only means Meta accepted the message; monitor delivered, read or failed for the result.
Copy the brief, fill in your sender and use case. Never paste your live token into an AI chat; keep it in a server environment variable.
Integrate my server with https://awam.io/developers. My sender is [Awam number / own coexistence number] and my use case is [appointments/orders/OTP/other]. Never request or paste a live API token in this chat; use a server environment variable. Each business needs its own Awam workspace and Settings → Connect your system API connection. Use the canonical Event API URL for the JSON schema below; the raw Webhook URL is for external providers with their own field names. Call GET /api/v1/account/{token} to inspect whatsapp.mode/status, integration.status, billing.subscription.messages_remaining, paid_balance_minor and otp.available. Configure approved templates and variable mappings on workflow stages (Awam templates for the shared number, customer WABA templates for coexistence). POST /api/v1/events/{token} with a unique stable event_id for each change, event matching a mapped external status, object.id, customer name/international phone/consent, details and scheduled_at when the stage template needs them. IMPORTANT: object.id is the stable order/booking ID generated by my system. If the selected stage template maps its customer-facing tracking variable to Awam's tracking_number variable, Awam displays object.id there; Awam's internal numeric order_id stays separate. Keep object.id unchanged across events for that order. event_id is different: use a unique value for each status-change event and reuse it only for retrying that exact event. For object.scheduled_at, send an absolute ISO 8601 timestamp with Z or a numeric offset; Awam stores UTC and displays appointment dates, reminders and booking times using the merchant's saved business timezone. Convert any timezone-free source-system time using that business's IANA timezone before sending. First POST captures a sample only: map its event value to a stage in Awam, then send a NEW event_id. 202 is not WhatsApp delivery. Poll GET /api/v1/messages/{token}?before_id=... for outcomes and GET /api/v1/responses/{token}?after_id=... for replies; persist cursors. For OTP on Awam's number, the workspace owner enables it on the API connection in Settings → Connect your system. Check otp.available=true. For the recommended managed flow POST /api/v1/otp/{token} with unique request_id, phone, purpose and consent:true (omit code); Awam generates and sends a six-digit code. Poll GET /api/v1/otp/{token}?request_id=... for message delivery only. On my server POST /api/v1/otp/{token}/verify with the same request_id, phone, purpose and code entered by the person. Only verified:true permits my app to complete signup/login. Keep request_id bound to my own pending user/session. A wrong code, expiry, fifth wrong attempt or reuse fails; verification is free, the message uses quota then paid overage. The legacy POST with a developer-generated code still works but my server must verify that code itself. Respect 429 Retry-After; handle paused connection, unavailable templates and blocked_balance. Show exact backend code, stage/status mapping, idempotent retries, safe test and failure handling. Ask for field names but never my live secret.