Agent-TS API

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

Base URL

http://localhost:8000    # Development
https://agent.smartpay.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

/healthpath

Check if the agent service is running and healthy.

Response

{
  "status": "healthy",
  "service": "smartpay-agent-ts",
  "activeConversations": 5
}

Example

curl http://localhost:8000/health

---

Clear Conversation

/api/v1/conversation/:phonepath

Clear the conversation history for a specific user.

Path Parameters

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

Response

{
  "success": true,
  "message": "Conversation history cleared for +23279123456"
}

Example

curl -X DELETE "http://localhost:8000/api/v1/conversation/+23279123456"

---

Compatibility WhatsApp Webhook

/api/v1/external/whatsapppath

Receive messages from a compatibility bridge used for local testing. Production traffic should use Kapso / Meta webhooks.

Request Body

eventstringbodyrequired

Event type: message, connected, disconnected

messagestringbody

Text message content

fromstringbody

Sender JID (e.g., 23279123456@c.us)

phoneE164stringbodyrequired

Phone in E.164 format (e.g., +23279123456)

messageTypestringbody

Message type: text, image, document

hasMediabooleanbody

Whether message contains media

mediaobjectbody

Media object with data, mimetype, filename, size

Text Message Request

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

Image Message Request (KYC)

{
  "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,).

Response

{
  "answer": "Your balance is 5,000 SLE",
  "status": "success"
}

Example

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)

/api/v1/webhooks/whatsapppath

Verify webhook with Meta WhatsApp Business API.

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

curl "http://localhost:8000/api/v1/webhooks/whatsapp?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=CHALLENGE"

---

Kapso / Meta WhatsApp Webhook (Messages)

/api/v1/webhooks/whatsapppath

Receive messages from Kapso's WhatsApp webhook, and also accepts forwarded Meta webhook payloads.

Request Body

Standard Meta webhook format:

{
  "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

/api/v1/notifications/whatsapppath

Send transaction notifications via WhatsApp (internal service use only).

Authentication

HMAC service authentication required:

X-Service-Name: wallet-core
X-Service-Timestamp: 1710072000
X-Service-Signature: <hex-hmac>

Request Body

phoneE164stringbodyrequired

Recipient phone in E.164 format

messagestringbody

Notification free-text body. Required unless interactive or template is provided.

interactiveobjectbody

Optional Kapso interactive payload for list menus, reply buttons, flows, or CTA URLs.

templateobjectbody

Optional approved WhatsApp template payload sent through Kapso.

transactionTypestringbody

Transaction type for receipt generation

metadataobjectbody

Transaction metadata for receipt

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

{
  "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

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

Response

{
  "success": true,
  "message": "Receipt image sent",
  "details": { "messageId": "msg_123" }
}

Example

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

{
  "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

Tools Reference

OpenAI function calling tools

Webhooks Guide

WhatsApp integration setup