> ## 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.

# Agent-TS API

> REST API endpoints for the OLIVE Agent-TS service

# Agent-TS API Reference

The Agent-TS service exposes REST endpoints for WhatsApp integration, health monitoring, and internal notifications.

## Base URL

```
http://localhost:8000    # Development
https://agent.olive.example.com  # Production
```

## Endpoints Overview

| Method   | Endpoint                         | Description                    | Auth         |
| -------- | -------------------------------- | ------------------------------ | ------------ |
| `GET`    | `/health`                        | Health check                   | None         |
| `DELETE` | `/api/v1/conversation/:phone`    | Clear conversation             | None         |
| `GET`    | `/api/v1/webhooks/whatsapp`      | Meta webhook verification      | Verify Token |
| `POST`   | `/api/v1/webhooks/whatsapp`      | Kapso / Meta WhatsApp messages | None         |
| `POST`   | `/api/v1/external/whatsapp`      | Compatibility test bridge      | None         |
| `POST`   | `/api/v1/notifications/whatsapp` | Internal notifications         | HMAC         |

***

## Health Check

<ParamField header="GET" path="/health">
  Check if the agent service is running and healthy.
</ParamField>

### Response

```json theme={null}
{
  "status": "healthy",
  "service": "olive-agent-ts",
  "activeConversations": 5
}
```

### Example

```bash theme={null}
curl http://localhost:8000/health
```

***

## Clear Conversation

<ParamField header="DELETE" path="/api/v1/conversation/:phone">
  Clear the conversation history for a specific user.
</ParamField>

### Path Parameters

| Parameter | Type   | Description                          |
| --------- | ------ | ------------------------------------ |
| `phone`   | string | Phone number (E.164 or local format) |

### Response

<Tabs>
  <Tab title="Success (200)">
    ```json theme={null}
    {
      "success": true,
      "message": "Conversation history cleared for +23279123456"
    }
    ```
  </Tab>

  <Tab title="Not Found (404)">
    ```json theme={null}
    {
      "success": false,
      "message": "No conversation found for +23279123456"
    }
    ```
  </Tab>
</Tabs>

### Example

```bash theme={null}
curl -X DELETE "http://localhost:8000/api/v1/conversation/+23279123456"
```

***

## Compatibility WhatsApp Webhook

<ParamField header="POST" path="/api/v1/external/whatsapp">
  Receive messages from a compatibility bridge used for local testing. Production traffic should use Kapso / Meta webhooks.
</ParamField>

### Request Body

<ParamField body="event" type="string" required>
  Event type: `message`, `connected`, `disconnected`
</ParamField>

<ParamField body="message" type="string">
  Text message content
</ParamField>

<ParamField body="from" type="string">
  Sender JID (e.g., `23279123456@c.us`)
</ParamField>

<ParamField body="phoneE164" type="string" required>
  Phone in E.164 format (e.g., `+23279123456`)
</ParamField>

<ParamField body="messageType" type="string">
  Message type: `text`, `image`, `document`
</ParamField>

<ParamField body="hasMedia" type="boolean">
  Whether message contains media
</ParamField>

<ParamField body="media" type="object">
  Media object with `data`, `mimetype`, `filename`, `size`
</ParamField>

### Text Message Request

```json theme={null}
{
  "event": "message",
  "message": "What is my balance?",
  "from": "23279123456@c.us",
  "phoneE164": "+23279123456"
}
```

### Image Message Request (KYC)

```json theme={null}
{
  "event": "message",
  "messageType": "image",
  "hasMedia": true,
  "phoneE164": "+23279123456",
  "message": "Here is my ID",
  "media": {
    "data": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
    "mimetype": "image/jpeg",
    "filename": "id_card_front.jpg",
    "size": 52643
  }
}
```

<Warning>
  The `media.data` field **must** include the data URI prefix (`data:image/jpeg;base64,`).
</Warning>

### Response

```json theme={null}
{
  "answer": "Your balance is 5,000 SLE",
  "status": "success"
}
```

### Example

```bash theme={null}
curl -X POST "http://localhost:8000/api/v1/external/whatsapp" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "message",
    "message": "check my balance",
    "phoneE164": "+23279123456"
  }'
```

***

## Meta WhatsApp Webhook (Verification)

<ParamField header="GET" path="/api/v1/webhooks/whatsapp">
  Verify webhook with Meta WhatsApp Business API.
</ParamField>

### Query Parameters

| Parameter          | Type   | Description            |
| ------------------ | ------ | ---------------------- |
| `hub.mode`         | string | Must be `subscribe`    |
| `hub.verify_token` | string | Your verify token      |
| `hub.challenge`    | string | Challenge to echo back |

### Response

Returns the `hub.challenge` value on success, or `403` on failure.

### Example

```bash theme={null}
curl "http://localhost:8000/api/v1/webhooks/whatsapp?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=CHALLENGE"
```

***

## Kapso / Meta WhatsApp Webhook (Messages)

<ParamField header="POST" path="/api/v1/webhooks/whatsapp">
  Receive messages from Kapso's WhatsApp webhook, and also accepts forwarded Meta webhook payloads.
</ParamField>

### Request Body

Standard Meta webhook format:

```json theme={null}
{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": "15551234567",
          "phone_number_id": "PHONE_NUMBER_ID"
        },
        "contacts": [{
          "profile": { "name": "John Doe" },
          "wa_id": "23279123456"
        }],
        "messages": [{
          "from": "23279123456",
          "id": "wamid.xxx",
          "timestamp": "1234567890",
          "type": "text",
          "text": { "body": "What is my balance?" }
        }]
      }
    }]
  }]
}
```

### Response

Returns `200 OK` on success.

***

## Internal Notifications

<ParamField header="POST" path="/api/v1/notifications/whatsapp">
  Send transaction notifications via WhatsApp (internal service use only).
</ParamField>

### Authentication

HMAC service authentication required:

```http theme={null}
X-Service-Name: wallet-core
X-Service-Timestamp: 1710072000
X-Service-Signature: <hex-hmac>
```

### Request Body

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

<ParamField body="message" type="string">
  Notification free-text body. Required unless `interactive` or `template` is provided.
</ParamField>

<ParamField body="interactive" type="object">
  Optional Kapso interactive payload for list menus, reply buttons, flows, or CTA URLs.
</ParamField>

<ParamField body="template" type="object">
  Optional approved WhatsApp template payload sent through Kapso.
</ParamField>

<ParamField body="transactionType" type="string">
  Transaction type for receipt generation
</ParamField>

<ParamField body="metadata" type="object">
  Transaction metadata for receipt
</ParamField>

### Transaction Types

| Type            | Description           |
| --------------- | --------------------- |
| `pos_payment`   | POS terminal payment  |
| `pos_refund`    | POS refund            |
| `agent_cash_in` | Agent cash-in         |
| `p2p_transfer`  | Peer-to-peer transfer |
| `cash_out`      | Cash withdrawal       |

### Default Delivery Policy

| Transaction / event                                                      | Default delivery                                    |
| ------------------------------------------------------------------------ | --------------------------------------------------- |
| gateway credential notifications                                         | free text                                           |
| `subscriber_registration`                                                | interactive buttons                                 |
| `fund_from_vult`                                                         | interactive buttons                                 |
| `transfer_to_vult`                                                       | interactive buttons                                 |
| `processor_transfer`                                                     | interactive buttons                                 |
| `account_unblocked`                                                      | interactive buttons                                 |
| `child_card_created`                                                     | interactive buttons                                 |
| `card_unblocked`                                                         | interactive buttons                                 |
| security alerts, OTPs, VIP alerts, compliance alerts                     | free text                                           |
| `pos_payment`, `pos_refund`, `agent_cash_in`, `p2p_transfer`, `cash_out` | receipt image with caption when metadata is present |

Services can always override the default by sending an explicit `interactive` or `template` payload.

### Request Example

```json theme={null}
{
  "phoneE164": "+23279123456",
  "message": "You received 5,000 SLE from John Doe",
  "transactionType": "p2p_transfer",
  "metadata": {
    "amount": 5000,
    "currency": "SLE",
    "sender_name": "John Doe",
    "transaction_id": "txn_abc123"
  }
}
```

### Template Example

```json theme={null}
{
  "phoneE164": "+23279123456",
  "template": {
    "name": "payment_reminder",
    "languageCode": "en",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "John" },
          { "type": "text", "text": "SLE 500" }
        ]
      }
    ]
  }
}
```

### Response

```json theme={null}
{
  "success": true,
  "message": "Receipt image sent",
  "details": { "messageId": "msg_123" }
}
```

### Example

```bash theme={null}
curl -X POST "http://localhost:8000/api/v1/notifications/whatsapp" \
  -H "X-Service-Name: wallet-core" \
  -H "X-Service-Timestamp: 1710072000" \
  -H "X-Service-Signature: 5d41402abc4b2a..." \
  -H "Content-Type: application/json" \
  -d '{
    "phoneE164": "+23279123456",
    "message": "Payment received: 5,000 SLE"
  }'
```

***

## Error Responses

### Standard Error Format

```json theme={null}
{
  "error": "Error description",
  "status": "error"
}
```

### Common Errors

| Status | Error                           | Description       |
| ------ | ------------------------------- | ----------------- |
| 400    | `Phone number required`         | Missing phoneE164 |
| 401    | `Service authentication failed` | Invalid HMAC      |
| 500    | `Error processing webhook`      | Internal error    |
| 503    | `Agent not initialized`         | Service starting  |

## Next Steps

<CardGroup cols={2}>
  <Card title="Tools Reference" icon="wrench" href="/agent-ts/tools">
    OpenAI function calling tools
  </Card>

  <Card title="Webhooks Guide" icon="webhook" href="/agent-ts/webhooks">
    WhatsApp integration setup
  </Card>
</CardGroup>