Docs

How WhatsApp works

Link a WhatsApp number to talks, send and receive messages through the API, and put an AI agent on it.

The building blocks

PlanMonthly price for one linked numberGET /v1/whatsapp/plans
SubscriptionOne per number. Holds its status, link and expiryPOST /v1/whatsapp/subscriptions
LinkHow the number connects: QR code or Meta business accountgenerate-qr · connect-official
MessagesEach message draws per_message_credits from your walletPOST /v1/whatsapp/send
AgentsOptional AI that replies on the numberPOST /v1/whatsapp/agents

Link a number

Option A: scan a QR code

  1. Get a code

    POST /v1/whatsapp/subscriptions/{id}/generate-qr returns qr_code and qr_code_url.

  2. Scan it

    On the business phone: WhatsApp → Settings → Linked devices → Link a device.

  3. Confirm

    Poll GET /v1/whatsapp/subscriptions/{id}/link-status every few seconds until status is connected.

Option B: your WhatsApp Business Platform account

Already on Meta's official platform? POST /v1/whatsapp/subscriptions/{id}/connect-official with phone_number_id, waba_id and access_token. talks checks them with Meta before saving.

Warning: If the phone logs out of WhatsApp or the app is removed, a QR link drops. Check link-status before big sends and re-link if needed.

Send messages

textcontent
image · documentmedia_url (from POST /v1/whatsapp/media), media_filename, content as caption
locationlatitude, longitude, location_name, location_address

Add scheduled_at to send later, and cancel before it goes with DELETE /v1/whatsapp/messages/{message_id}. Check any message with GET /v1/whatsapp/messages/{message_id}.

Receive messages

Customer replies arrive on your webhook as they come in, and the full history for a number is at GET /v1/whatsapp/subscriptions/{id}/messages.

Put an AI agent on it

  1. Create

    POST /v1/whatsapp/agents with a system_prompt, business facts in system_context and a greeting_message.

  2. Give it tools

    POST /v1/whatsapp/agents/{id}/tools so it can call your APIs for stock, bookings or payments.

  3. Test privately

    POST /v1/whatsapp/agents/{id}/chat lets you talk to it without touching real customers. The reply shows which tools it called.

    { "message": "Do you have braids on Saturday?", "customer_name": "Test" }

  4. Go live

    POST /v1/whatsapp/agents/{id}/activate. Use auto_reply_include and auto_reply_exclude to choose who it answers.

  5. Watch it

    GET /v1/whatsapp/agents/{id}/conversations and /stats show every chat, response times and tool use.

Tip: Not sure which AI model to use? POST /v1/whatsapp/agents/models/auto-select benchmarks them and returns the best fit for speed and quality.

Keep it running

Each subscription has expires_at. Renew with POST /v1/whatsapp/subscriptions/{id}/renew, or cancel with DELETE /v1/whatsapp/subscriptions/{id}.

Was this page helpful?
Powered by StdioX Labs