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

# WhatsApp Webhook

> Kapso-first WhatsApp message webhooks

<Info>
  Receive and process WhatsApp messages via Agent-TS. Kapso is the supported transport; `/api/v1/external/whatsapp` remains only as a compatibility test bridge.
</Info>

## Endpoints

| Method | Endpoint                    | Description               |
| ------ | --------------------------- | ------------------------- |
| `POST` | `/api/v1/external/whatsapp` | Compatibility test bridge |
| `GET`  | `/api/v1/webhooks/whatsapp` | Meta webhook verification |
| `POST` | `/api/v1/webhooks/whatsapp` | Meta webhook messages     |

***

## External Client Request

<ParamField body="event" type="string" required>
  Event type (e.g., `message`)
</ParamField>

<ParamField body="message" type="string" required>
  Message content from user
</ParamField>

<ParamField body="from" type="string" required>
  WhatsApp ID (e.g., `23279648205@c.us`)
</ParamField>

<ParamField body="phoneE164" type="string" required>
  Phone number in E.164 format
</ParamField>

***

## Response

<ResponseField name="answer" type="string">
  Agent response message
</ResponseField>

<ResponseField name="status" type="string">
  Processing status (`success`, `error`)
</ResponseField>

***

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://demo.api.vultlocal.com/api/v1/external/whatsapp" \
    -H "Content-Type: application/json" \
    -d '{
      "event": "message",
      "message": "What is my balance?",
      "from": "23279648205@c.us",
      "phoneE164": "+23279648205"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "answer": "Your balance is 5,000 SLE",
    "status": "success"
  }
  ```

  ```json 200 Unregistered User theme={null}
  {
    "answer": "You are not registered. Reply with your full name to register.",
    "status": "success"
  }
  ```

  ```json 400 Invalid Request theme={null}
  {
    "error": "Missing required field: message",
    "status": "error"
  }
  ```
</ResponseExample>

***

## Meta Business API

### Verification (GET)

Meta sends a verification request when setting up the webhook:

```
GET /api/v1/webhooks/whatsapp?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=CHALLENGE
```

Return `hub.challenge` if `hub.verify_token` matches.

### Messages (POST)

Meta sends incoming messages as POST requests with the message payload.

***

## Related

<Card title="Agent-TS Webhooks" icon="book" href="/agent-ts/webhooks">
  Detailed webhook configuration and message handling
</Card>


## OpenAPI

````yaml olive-openapi.json POST /external/whatsapp
openapi: 3.0.0
info:
  description: >-
    API Gateway for OLIVE NFC Card Payment System - Comprehensive payment, card
    management, agent operations, and admin authentication. All /api/v1 routes
    require authentication using either API Key or JWT token.
  title: OLIVE NFC Card Payment API
  termsOfService: http://swagger.io/terms/
  contact:
    name: API Support
    email: support@olive.sl
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
  - url: https://olive-gateway-a6ba.onrender.com/api/v1
security: []
paths:
  /external/whatsapp:
    post:
      tags:
        - Webhooks
      summary: WhatsApp Webhook
      description: WhatsApp message webhooks
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                event:
                  type: string
                message:
                  type: string
                from:
                  type: string
                phoneE164:
                  type: string
              required:
                - event
                - message
                - from
                - phoneE164
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

````