Skip to content

Get started

Quickstart: send your first WhatsApp message

In five steps you create an API key, read your contacts, start a WhatsApp conversation by phone number, send a reply and receive incoming messages on your own server.

1. How do I create an API key?

In the app, open API keys, enter a name and choose the write scope (the steps below send messages, which a read key cannot do). Copy the key that starts with pk_live_: it is shown only once. Store it in an environment variable:

export WHATSAPPX_API_KEY="pk_live_…"

2. Make your first request: list contacts

curl "https://whatsappx.si/api/v1/contacts" \
  -H "Authorization: Bearer $WHATSAPPX_API_KEY"

A 200 with a JSON array (possibly empty) means your key works. A 401 with invalid or expired API key means the key is wrong, revoked or expired.

3. Start a conversation and send the first message

curl -X POST "https://whatsappx.si/api/conversations" \
  -H "Authorization: Bearer $WHATSAPPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+15550100123", "body": "Hi Jordan, your order is ready for pickup."}'

The response contains the conversation (keep its id) and the sent message. Calling it again with the same phone number returns the same conversation. A 409 with whatsapp is not connected means the workspace’s WhatsApp connection is not ready. On a Cloud API number, Meta delivers free-form text only within 24 hours of the customer’s last message (see Send a message).

4. Reply in the conversation

curl -X POST "https://whatsappx.si/api/conversations/$CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $WHATSAPPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body": "We are open until 6 pm today."}'

5. How do I receive replies?

Register an HTTPS endpoint as an outbound webhook in the app (Webhooks, owner or admin). From then on, every incoming message is posted to your URL:

  • On a number linked by QR code, the body is a whatsappx.si JSON object with event: "message.inbound" and the header X-Whatsappx-Event: scan.whatsapp.
  • On a Cloud API number, the body is Meta’s original webhook payload with X-Whatsappx-Event: meta.whatsapp.

Every delivery is signed with X-Hub-Signature-256. See Webhooks for signature verification and Webhook events for the payloads.

To read history instead, call List messages with the conversation id.

Next steps