> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Worked samples

> Read → update → re-read the conversational-automation config (ice breakers, slash commands, welcome toggle), an interactive send with the full envelope, the test-account analytics envelope, and validation errors.

## 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](/sdks/python) 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](/guides/api-recipes). 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

<Note>
  `GET /api/v1/whatsapp/conversational-automation`
</Note>

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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.orbit.devotel.io/api/v1/whatsapp/conversational-automation" \
    -H "X-API-Key: dv_live_sk_your_key_here"
  ```

  ```typescript Node.js theme={null}
  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());
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

### 2. Update the config (full desired state)

<Note>
  `PUT /api/v1/whatsapp/conversational-automation`
</Note>

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**

```json theme={null}
{
  "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"
    }
  ]
}
```

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {
      "ok": true
    },
    "meta": {
      "request_id": "req_wa_ca_put",
      "timestamp": "2026-08-30T12:00:05.000Z"
    }
  }
  ```
</ResponseExample>

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:

```json 422 theme={null}
{
  "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

<Note>
  `POST /api/v1/whatsapp/messages/send-interactive`
</Note>

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**

```json theme={null}
{
  "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" } }
    ]
  }
}
```

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {
      "message_id": "wamid.HBgNMTIzNDU2Nzg5MGFiY2Rl",
      "to": "+14155552671",
      "status": "accepted"
    },
    "meta": {
      "request_id": "req_wa_ix_send",
      "timestamp": "2026-08-30T12:01:00.000Z"
    }
  }
  ```
</ResponseExample>

### 4. Test-account analytics KPIs

<Note>
  `GET /api/v1/whatsapp/test-account/analytics`
</Note>

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.

<ResponseExample>
  ```json 200 theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>