API Reference

Complete list of Tavio API endpoints. All endpoints require authentication unless noted otherwise. Base URL: https://bankmind.aihookd.site

Chat

Method	Path	Description	Auth
POST	/api/chat	Send a message and receive an AI response	Bearer token
POST	/api/v1/widget/init	Initialize a widget chat session	Widget token
POST	/api/v1/widget/message	Send a widget message (SSE streaming response)	Widget token

Conversations

Method	Path	Description	Auth
GET	/api/conversations	List all conversations for your tenant	Bearer token
GET	/api/conversations/[id]	Get a specific conversation by ID	Bearer token
GET	/api/conversations/[id]/messages	List messages in a conversation	Bearer token

Analytics

Method	Path	Description	Auth
GET	/api/analytics	Get analytics metrics (intents, confidence, resolution)	Bearer token

Knowledge Base

Method	Path	Description	Auth
GET	/api/knowledge	List knowledge documents	Bearer token
POST	/api/knowledge	Upload a knowledge document for RAG indexing	Bearer token
GET	/api/knowledge/sources	List knowledge sources (URLs, PDFs)	Bearer token
POST	/api/knowledge/sources	Add a knowledge source URL for crawling	Bearer token

Channels

Method	Path	Description	Auth
GET	/api/tenant/channels	List configured channels	Bearer token
GET	/api/tenant/channels/[channelId]	Get channel configuration	Bearer token
PUT	/api/tenant/channels/[channelId]	Update channel configuration	Bearer token
POST	/api/tenant/voices	Create or update voice configuration	Bearer token
GET	/api/tenant/voices	Get voice configuration	Bearer token

Agents & Team

Method	Path	Description	Auth
GET	/api/agents	List team members	Bearer token
POST	/api/agents	Invite a team member	Bearer token (admin)
PUT	/api/agents	Update member role or remove member	Bearer token (admin)

Escalations

Method	Path	Description	Auth
GET	/api/escalations	List escalation tickets	Bearer token
POST	/api/escalations	Create an escalation ticket	Bearer token
PUT	/api/escalations	Assign or resolve an escalation	Bearer token

Channel Webhooks

Method	Path	Description	Auth
POST	/api/channels/whatsapp	WhatsApp incoming message webhook	Meta signature
POST	/api/channels/sms	SMS incoming message webhook	Provider signature
POST	/api/channels/ussd	USSD session callback	Provider signature
POST	/api/channels/twitter	Twitter mention webhook	OAuth signature
POST	/api/v1/voice/inbound	Twilio voice inbound webhook	Twilio signature
POST	/api/v1/voice/status	Twilio call status callback	Twilio signature
POST	/api/v1/channels/telegram/webhook	Telegram bot message webhook	Secret token header
POST	/api/v1/channels/meta/webhook	Meta webhook (Messenger & Instagram)	Meta signature

Example: Send a Chat Message

Request

bash

curl -X POST https://bankmind.aihookd.site/api/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the requirements for a personal loan?",
    "conversationId": "conv_abc123",
    "channel": "widget"
  }'

Response (200 OK)

json

{
  "response": "To apply for a personal loan, you'll need: 1) A valid national ID, 2) Proof of income (last 3 payslips), 3) Bank statements for the last 6 months, 4) A minimum monthly income of KES 30,000.",
  "conversationId": "conv_abc123",
  "messageId": "msg_xyz789",
  "metadata": {
    "intent": "loan_inquiry",
    "confidence": 0.94,
    "agentType": "loan",
    "tokensUsed": 87
  }
}

Example: List Conversations

Request

bash

curl https://bankmind.aihookd.site/api/conversations \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

json

{
  "conversations": [
    {
      "id": "conv_abc123",
      "channel": "whatsapp",
      "status": "active",
      "customer_phone": "+254712345678",
      "message_count": 12,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:45:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Error Format

All errors follow a consistent JSON format:

Error response

json

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}

Status	Code	Meaning
401	AUTH_INVALID	Missing or invalid credentials
403	FORBIDDEN	Insufficient permissions
404	NOT_FOUND	Resource not found
422	VALIDATION	Invalid request body
429	RATE_LIMIT	Too many requests
500	INTERNAL	Server error
502	EXTERNAL	Third-party service error

API Reference

Complete list of Tavio API endpoints. All endpoints require authentication unless noted otherwise. Base URL: https://bankmind.aihookd.site

Chat

Method	Path	Description	Auth
POST	/api/chat	Send a message and receive an AI response	Bearer token
POST	/api/v1/widget/init	Initialize a widget chat session	Widget token
POST	/api/v1/widget/message	Send a widget message (SSE streaming response)	Widget token

Conversations

Method	Path	Description	Auth
GET	/api/conversations	List all conversations for your tenant	Bearer token
GET	/api/conversations/[id]	Get a specific conversation by ID	Bearer token
GET	/api/conversations/[id]/messages	List messages in a conversation	Bearer token

Analytics

Method	Path	Description	Auth
GET	/api/analytics	Get analytics metrics (intents, confidence, resolution)	Bearer token

Knowledge Base

Method	Path	Description	Auth
GET	/api/knowledge	List knowledge documents	Bearer token
POST	/api/knowledge	Upload a knowledge document for RAG indexing	Bearer token
GET	/api/knowledge/sources	List knowledge sources (URLs, PDFs)	Bearer token
POST	/api/knowledge/sources	Add a knowledge source URL for crawling	Bearer token

Channels

Method	Path	Description	Auth
GET	/api/tenant/channels	List configured channels	Bearer token
GET	/api/tenant/channels/[channelId]	Get channel configuration	Bearer token
PUT	/api/tenant/channels/[channelId]	Update channel configuration	Bearer token
POST	/api/tenant/voices	Create or update voice configuration	Bearer token
GET	/api/tenant/voices	Get voice configuration	Bearer token

Agents & Team

Method	Path	Description	Auth
GET	/api/agents	List team members	Bearer token
POST	/api/agents	Invite a team member	Bearer token (admin)
PUT	/api/agents	Update member role or remove member	Bearer token (admin)

Escalations

Method	Path	Description	Auth
GET	/api/escalations	List escalation tickets	Bearer token
POST	/api/escalations	Create an escalation ticket	Bearer token
PUT	/api/escalations	Assign or resolve an escalation	Bearer token

Channel Webhooks

Method	Path	Description	Auth
POST	/api/channels/whatsapp	WhatsApp incoming message webhook	Meta signature
POST	/api/channels/sms	SMS incoming message webhook	Provider signature
POST	/api/channels/ussd	USSD session callback	Provider signature
POST	/api/channels/twitter	Twitter mention webhook	OAuth signature
POST	/api/v1/voice/inbound	Twilio voice inbound webhook	Twilio signature
POST	/api/v1/voice/status	Twilio call status callback	Twilio signature
POST	/api/v1/channels/telegram/webhook	Telegram bot message webhook	Secret token header
POST	/api/v1/channels/meta/webhook	Meta webhook (Messenger & Instagram)	Meta signature

Example: Send a Chat Message

Request

bash

curl -X POST https://bankmind.aihookd.site/api/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the requirements for a personal loan?",
    "conversationId": "conv_abc123",
    "channel": "widget"
  }'

Response (200 OK)

json

{
  "response": "To apply for a personal loan, you'll need: 1) A valid national ID, 2) Proof of income (last 3 payslips), 3) Bank statements for the last 6 months, 4) A minimum monthly income of KES 30,000.",
  "conversationId": "conv_abc123",
  "messageId": "msg_xyz789",
  "metadata": {
    "intent": "loan_inquiry",
    "confidence": 0.94,
    "agentType": "loan",
    "tokensUsed": 87
  }
}

Example: List Conversations

Request

bash

curl https://bankmind.aihookd.site/api/conversations \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

json

{
  "conversations": [
    {
      "id": "conv_abc123",
      "channel": "whatsapp",
      "status": "active",
      "customer_phone": "+254712345678",
      "message_count": 12,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:45:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Error Format

All errors follow a consistent JSON format:

Error response

json

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}

Status	Code	Meaning
401	AUTH_INVALID	Missing or invalid credentials
403	FORBIDDEN	Insufficient permissions
404	NOT_FOUND	Resource not found
422	VALIDATION	Invalid request body
429	RATE_LIMIT	Too many requests
500	INTERNAL	Server error
502	EXTERNAL	Third-party service error