Docs/

API reference

REST API v1

WhautX REST API

A JSON REST API for managing contacts, conversations, messages, campaigns, lead forms, and your knowledge base. All requests are scoped to your workspace and authenticated with an API key.

Base URL

https://www.whautx.com/api/v1

Authentication

Generate a key in Settings → Developer (OWNER or ADMIN only), then send it as a Bearer token on every request. The key is shown once at creation — store it securely.

Authorization: Bearer whautx_live_xxxxxxxxxxxx

Scopes

Each key carries one or more scopes. A request to an endpoint whose scope your key lacks returns 403 Forbidden.

contacts.readcontacts.writemessages.sendcampaigns.readcampaigns.writeforms.submitknowledge.read

Contacts

GET/contactscontacts.read

Paginated contact list, newest first. Use nextCursor for the next page.

Parameters

  • limitMax 200, default 50.
  • aftercreatedAt ISO cursor from a previous nextCursor.
  • searchMatches first/last name, phone, or email.
curl "https://www.whautx.com/api/v1/contacts?limit=50" \
  -H "Authorization: Bearer whautx_live_xxx"
GET/contacts/:idcontacts.read

Fetch a single contact by ID, including its tags.

curl "https://www.whautx.com/api/v1/contacts/CONTACT_ID" \
  -H "Authorization: Bearer whautx_live_xxx"
POST/contactscontacts.write

Find-or-create by phone. Returns 200 with created:false on a match, 201 with created:true on a new contact.

Parameters

  • phoneNumberrequiredE.164 phone, e.g. +971501234567.
  • firstNameOptional.
  • lastNameOptional.
  • emailOptional.
  • customFieldsOptional JSON object of custom attributes.
curl -X POST "https://www.whautx.com/api/v1/contacts" \
  -H "Authorization: Bearer whautx_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+971501234567","firstName":"Sara"}'
PATCH/contacts/:idcontacts.write

Partial update of a contact.

Parameters

  • firstName / lastName / emailAny subset.
  • optOutBoolean — suppress future messaging.
  • customFieldsJSON object; replaces the stored value.
  • tagIdsArray of tag IDs — replaces the contact’s tags.
curl -X PATCH "https://www.whautx.com/api/v1/contacts/CONTACT_ID" \
  -H "Authorization: Bearer whautx_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"optOut":true}'

Conversations

GET/conversationscontacts.read

List conversations — the latest message per contact phone, per WhatsApp account.

Parameters

  • limitMax 200, default 50.
curl "https://www.whautx.com/api/v1/conversations" \
  -H "Authorization: Bearer whautx_live_xxx"
GET/conversations/:contactPhone/messagescontacts.read

Paginated message thread for a contact phone on a specific account, oldest first.

Parameters

  • accountIdrequiredWhatsApp account ID (query param).
  • limitMax 200, default 50.
  • aftercreatedAt ISO cursor for the next page.
curl "https://www.whautx.com/api/v1/conversations/971501234567/messages?accountId=ACCOUNT_ID" \
  -H "Authorization: Bearer whautx_live_xxx"

Messages

POST/messagesmessages.send

Send a plain-text WhatsApp message. Text sends are only valid inside the 24-hour customer service window; start new conversations with a template campaign.

Parameters

  • accountIdrequiredSending WhatsApp account ID.
  • torequiredRecipient phone in E.164.
  • textrequiredMessage body, max 4096 characters.
curl -X POST "https://www.whautx.com/api/v1/messages" \
  -H "Authorization: Bearer whautx_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"accountId":"ACCOUNT_ID","to":"+971501234567","text":"Hello!"}'

Campaigns

GET/campaignscampaigns.read

List up to 100 campaigns, newest first.

Parameters

  • statusOptional filter, e.g. DRAFT, SCHEDULED, COMPLETED.
curl "https://www.whautx.com/api/v1/campaigns?status=DRAFT" \
  -H "Authorization: Bearer whautx_live_xxx"
POST/campaignscampaigns.write

Create a DRAFT campaign. Drafts are never sent automatically — start them from the app so an accidental call can’t blast recipients.

Parameters

  • namerequiredCampaign name.
  • accountIdrequiredSending WhatsApp account ID.
  • templateIdrequiredApproved template ID.
  • segmentIdOptional target segment.
  • scheduledAtOptional ISO datetime.
curl -X POST "https://www.whautx.com/api/v1/campaigns" \
  -H "Authorization: Bearer whautx_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"July promo","accountId":"ACCOUNT_ID","templateId":"TEMPLATE_ID"}'

Lead forms

POST/forms/:formId/submitforms.submit

Server-to-server lead form submission. Same payload as the hosted form; triggers any attached automation. Returns 400 with a fields map on validation errors.

Parameters

  • <form fields>Keys match the form’s configured field names.
curl -X POST "https://www.whautx.com/api/v1/forms/FORM_ID/submit" \
  -H "Authorization: Bearer whautx_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sara","phone":"+971501234567"}'

Knowledge base

GET/knowledgeknowledge.read

List knowledge base documents (metadata only — embeddings are never exposed).

curl "https://www.whautx.com/api/v1/knowledge" \
  -H "Authorization: Bearer whautx_live_xxx"

Live request logs, rate limits, and key management live in Settings → Developer. Questions? Email [email protected].