Worked samples

Worked request and response samples

Copy a request as written, substitute your own values, and compare the response envelope. The conversational-automation chain a WhatsApp admin runs: read the config → write the full desired state → re-read to verify. Every sample below pairs curl with raw Node and Python (fetch / requests) — the Node SDK’s client.request(method, path, body) escape hatch and the Python SDK take the same route shape. Template sends live elsewhere. The loop for approved-template sends (GET /templates → POST /api/v1/messages/whatsapp) is worked end to end in API recipes, task 13. This overlay covers the operations on this page: the WhatsApp-specific config surface, interactive sends, and test-account analytics.

1. Read the conversational-automation config

GET /api/v1/whatsapp/conversational-automation

This returns the first-open affordances on your organization’s default WhatsApp connection: the welcome-message toggle, up to four ice breakers (prompts), and the slash-command menu (commands) — the same object you send back on update.

curl -X GET "https://api.orbit.devotel.io/api/v1/whatsapp/conversational-automation" \
  -H "X-API-Key: dv_live_sk_your_key_here"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/whatsapp/conversational-automation",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
);
console.log(await res.json());

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get(
    "https://api.orbit.devotel.io/api/v1/whatsapp/conversational-automation",
    headers=headers,
)
print(r.json())

{
  "data": {
    "enable_welcome_message": true,
    "prompts": [
      "Track my order",
      "Talk to support",
      "See opening hours"
    ],
    "commands": [
      {
        "command_name": "order_status",
        "command_description": "Check where your order is"
      },
      {
        "command_name": "support",
        "command_description": "Open a support conversation"
      }
    ]
  },
  "meta": {
    "request_id": "req_wa_ca_get",
    "timestamp": "2026-08-30T12:00:00.000Z"
  }
}

2. Update the config (full desired state)

PUT /api/v1/whatsapp/conversational-automation

WhatsApp replaces each field present on the write, so send the complete desired state — omitting prompts clears the ice breakers rather than leaving them as they were. Owners and admins only. command_name must be lowercase letters, digits, and underscores (no spaces); the caps — at most four ice breakers of 80 characters each, at most 30 commands — are validated here, so a bad config returns a 422 before it reaches Meta. Request

{
  "enable_welcome_message": true,
  "prompts": [
    "Track my order",
    "Talk to support",
    "See opening hours"
  ],
  "commands": [
    {
      "command_name": "order_status",
      "command_description": "Check where your order is"
    },
    {
      "command_name": "support",
      "command_description": "Open a support conversation"
    }
  ]
}

{
  "data": {
    "ok": true
  },
  "meta": {
    "request_id": "req_wa_ca_put",
    "timestamp": "2026-08-30T12:00:05.000Z"
  }
}

Re-read with step 1 to confirm the state Meta accepted. A field violation comes back as 422 with the offending field in error.details — for example a command_name with a space or an upper-case letter:

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "Request validation failed.",
    "details": {
      "field": "commands.0.command_name"
    }
  },
  "meta": {
    "request_id": "req_wa_ca_err",
    "timestamp": "2026-08-30T12:00:06.000Z"
  }
}

3. Send an interactive message

POST /api/v1/whatsapp/messages/send-interactive

Inside the recipient’s 24-hour customer-service window you can send without a template. action.buttons takes up to three reply buttons; the tap returns on your inbound webhook as button_reply. A list menu (action.button + action.sections) is the alternative shape. Request

{
  "to": "+14155552671",
  "header": "Order status",
  "body": "Your order #4821 is packed. Choose an update:",
  "action": {
    "buttons": [
      { "type": "reply", "reply": { "id": "track", "title": "Track it" } },
      { "type": "reply", "reply": { "id": "change", "title": "Change delivery" } }
    ]
  }
}

{
  "data": {
    "message_id": "wamid.HBgNMTIzNDU2Nzg5MGFiY2Rl",
    "to": "+14155552671",
    "status": "accepted"
  },
  "meta": {
    "request_id": "req_wa_ix_send",
    "timestamp": "2026-08-30T12:01:00.000Z"
  }
}

4. Test-account analytics KPIs

GET /api/v1/whatsapp/test-account/analytics

Pre-aggregated counts for the test-account analytics card in the dashboard, scoped to your OTP-verified test recipient. Read-only aggregate with no provider or billing side-effect. daily holds up to 30 data points, oldest first.

{
  "data": {
    "kpis": {
      "sent": 128,
      "delivered": 121,
      "read": 87
    },
    "daily": [
      { "date": "2026-08-29", "sent": 6, "delivered": 6 },
      { "date": "2026-08-30", "sent": 4, "delivered": 4 }
    ]
  },
  "meta": {
    "request_id": "req_wa_stats",
    "timestamp": "2026-08-30T12:02:00.000Z"
  }
}

API Reference

All Endpoints

Worked request and response samples

1. Read the conversational-automation config

2. Update the config (full desired state)

3. Send an interactive message

4. Test-account analytics KPIs

​Worked request and response samples

​1. Read the conversational-automation config

​2. Update the config (full desired state)

​3. Send an interactive message

​4. Test-account analytics KPIs

Worked request and response samples

1. Read the conversational-automation config

2. Update the config (full desired state)

3. Send an interactive message

4. Test-account analytics KPIs