REST API Reference

The AgentApiController provides REST endpoints for the Prophunt Webserver to communicate with Hexabot.

Base URL

http://localhost:4000/agent-api

Authentication

Currently, the API is internal (webserver to Hexabot). Add authentication middleware as needed:

// Example: API Key authentication
@UseGuards(ApiKeyGuard)
@Controller('agent-api')
export class AgentApiController { ... }

Endpoints

1. Send System Message

POST /agent-api/send-message

Send a predefined system message to a conversation (payment success, document uploaded, etc.).

Request Body

{
  taskId?: string;           // Either taskId OR verificationId required
  verificationId?: string;
  agentId: string;           // 'bgv', 'loan', 'listing'
  messageType: string;       // See supported types below
  data?: any;                // Additional data for message template
}

Supported Message Types

Type	Description	Data Fields
`payment_success`	Payment received confirmation	`amount`, `transactionId`
`payment_failed`	Payment failed notice	`retryUrl`
`doc_uploaded`	Document upload confirmation	`documentType`
`doc_rejected`	Document rejection notice	`reason`
`verification_in_progress`	Verification started	-
`verification_completed`	Verification done	`reportUrl`
`verification_failed`	Verification failed	`reason`

Example Request

curl -X POST http://localhost:4000/agent-api/send-message \
  -H "Content-Type: application/json" \
  -d '{
    "taskId": "bgv_user123_1234567890",
    "agentId": "bgv",
    "messageType": "payment_success",
    "data": {
      "amount": 499,
      "transactionId": "TXN_ABC123"
    }
  }'

Response

{
  "success": true,
  "messageId": "msg_xyz",
  "conversationId": "conv_abc",
  "taskId": "bgv_user123_1234567890"
}

Error Responses

// 404 - Conversation not found
{
  "statusCode": 404,
  "message": "Conversation not found"
}

// 400 - Missing required fields
{
  "statusCode": 400,
  "message": "Either taskId or verificationId is required"
}

2. Send Custom Message

POST /agent-api/send-custom

Send a fully custom message with complete control over content.

Request Body

{
  taskId?: string;
  verificationId?: string;
  message: MessageEnvelope;  // Full message object
}

Message Envelope Types

// Text message
{
  type: 'text',
  text: 'Your custom message here'
}

// Message with buttons
{
  type: 'buttons',
  text: 'Choose an option:',
  buttons: [
    {
      type: 'web_url',
      title: 'Click Here',
      url: 'https://example.com'
    },
    {
      type: 'postback',
      title: 'Send Event',
      payload: 'EVENT_NAME'
    }
  ]
}

// Quick replies
{
  type: 'quick_replies',
  text: 'Quick question?',
  quick_replies: [
    { title: 'Yes', payload: 'YES' },
    { title: 'No', payload: 'NO' }
  ]
}

// Custom payload (modals, forms, etc.)
{
  type: 'custom',
  custom_payload: {
    type: 'OPEN_MODAL',
    modal_id: 'payment_modal',
    data: { amount: 500 }
  }
}

Example Request

curl -X POST http://localhost:4000/agent-api/send-custom \
  -H "Content-Type: application/json" \
  -d '{
    "taskId": "bgv_user123_1234567890",
    "message": {
      "type": "buttons",
      "text": "Please select verification type:",
      "buttons": [
        {
          "type": "postback",
          "title": "Standard BGV",
          "payload": "BGV_STANDARD"
        },
        {
          "type": "postback",
          "title": "Express BGV",
          "payload": "BGV_EXPRESS"
        }
      ]
    }
  }'

Response

{
  "success": true,
  "messageId": "msg_xyz"
}

3. Get Conversation History

GET /agent-api/conversation/:taskId/history

Retrieve full conversation history for a task.

URL Parameters

taskId (string, required) - The conversation's task ID

Example Request

curl http://localhost:4000/agent-api/conversation/bgv_user123_1234567890/history

Response

{
  "conversationId": "conv_abc123",
  "taskId": "bgv_user123_1234567890",
  "verificationId": "VER_12345",
  "agentId": "bgv",
  "state": "VERIFICATION_IN_PROGRESS",
  "messages": [
    {
      "id": "msg_001",
      "message": {
        "text": "Welcome to BGV!"
      },
      "createdAt": "2025-12-05T10:00:00Z",
      "read": true
    },
    {
      "id": "msg_002",
      "message": {
        "text": "Please upload PAN"
      },
      "createdAt": "2025-12-05T10:01:00Z",
      "read": true
    }
  ]
}

4. Link Verification ID

POST /agent-api/link-verification

Link an external verification ID to an existing conversation.

Request Body

{
  taskId: string;           // Hexabot's internal task ID
  verificationId: string;   // Your external verification ID
}

Example Request

curl -X POST http://localhost:4000/agent-api/link-verification \
  -H "Content-Type: application/json" \
  -d '{
    "taskId": "bgv_user123_1234567890",
    "verificationId": "VER_PROPHUNT_12345"
  }'

Response

{
  "success": true,
  "conversationId": "conv_abc123",
  "taskId": "bgv_user123_1234567890",
  "verificationId": "VER_PROPHUNT_12345"
}

Use Case

When webserver creates a verification record, it can link the webserver's verification ID to Hexabot's task ID:

// Webserver code
const verificationId = await db.createVerification({ userId, panNumber });

// Link to Hexabot
await axios.post('http://hexabot:4000/agent-api/link-verification', {
  taskId: hexabotTaskId,
  verificationId: verificationId
});

// Now you can use verificationId in future calls
await axios.post('http://hexabot:4000/agent-api/send-message', {
  verificationId: verificationId,  // Instead of taskId
  agentId: 'bgv',
  messageType: 'verification_completed'
});

5. Update Conversation State

POST /agent-api/conversation/:taskId/state

Update the conversation state and add custom data to context.

URL Parameters

taskId (string, required)

Request Body

{
  state: string;     // New state value
  data?: any;        // Additional context data
}

Example Request

curl -X POST http://localhost:4000/agent-api/conversation/bgv_user123_1234567890/state \
  -H "Content-Type: application/json" \
  -d '{
    "state": "AWAITING_PAYMENT",
    "data": {
      "paymentAmount": 499,
      "paymentDueDate": "2025-12-10"
    }
  }'

Response

{
  "success": true,
  "conversationId": "conv_abc123",
  "taskId": "bgv_user123_1234567890",
  "state": "AWAITING_PAYMENT"
}

6. Get Conversation Details

GET /agent-api/conversation/:taskId

Get full conversation details including context.

URL Parameters

taskId (string, required)

Example Request

curl http://localhost:4000/agent-api/conversation/bgv_user123_1234567890

Response

{
  "conversationId": "conv_abc123",
  "taskId": "bgv_user123_1234567890",
  "verificationId": "VER_12345",
  "agentId": "bgv",
  "state": "AWAITING_PAYMENT",
  "active": true,
  "sender": "user123",
  "createdAt": "2025-12-05T10:00:00Z",
  "lastMessageAt": "2025-12-05T10:30:00Z",
  "context": {
    "vars": {
      "channelId": "prophunt_bgv",
      "agentId": "bgv",
      "taskId": "bgv_user123_1234567890",
      "verificationId": "VER_12345",
      "state": "AWAITING_PAYMENT",
      "panCardUploaded": true,
      "panNumber": "ABCDE1234F",
      "paymentAmount": 499
    }
  }
}

Integration Examples

Python (Webserver)

import requests

HEXABOT_API = "http://localhost:4000/agent-api"

def notify_payment_success(task_id, amount, transaction_id):
    response = requests.post(
        f"{HEXABOT_API}/send-message",
        json={
            "taskId": task_id,
            "agentId": "bgv",
            "messageType": "payment_success",
            "data": {
                "amount": amount,
                "transactionId": transaction_id
            }
        }
    )
    return response.json()

def notify_verification_complete(verification_id, report_url):
    response = requests.post(
        f"{HEXABOT_API}/send-message",
        json={
            "verificationId": verification_id,
            "agentId": "bgv",
            "messageType": "verification_completed",
            "data": {
                "reportUrl": report_url
            }
        }
    )
    return response.json()

Node.js (Webserver)

const axios = require('axios');

const HEXABOT_API = 'http://localhost:4000/agent-api';

async function notifyPaymentSuccess(taskId, amount, transactionId) {
  const response = await axios.post(`${HEXABOT_API}/send-message`, {
    taskId,
    agentId: 'bgv',
    messageType: 'payment_success',
    data: { amount, transactionId }
  });
  return response.data;
}

async function linkVerification(taskId, verificationId) {
  const response = await axios.post(`${HEXABOT_API}/link-verification`, {
    taskId,
    verificationId
  });
  return response.data;
}

async function getConversationHistory(taskId) {
  const response = await axios.get(
    `${HEXABOT_API}/conversation/${taskId}/history`
  );
  return response.data;
}

PHP (Webserver)

<?php
function sendToHexabot($taskId, $messageType, $data = []) {
    $url = 'http://localhost:4000/agent-api/send-message';
    
    $payload = [
        'taskId' => $taskId,
        'agentId' => 'bgv',
        'messageType' => $messageType,
        'data' => $data
    ];
    
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Usage
sendToHexabot('bgv_user123_123', 'payment_success', [
    'amount' => 499,
    'transactionId' => 'TXN_123'
]);
?>

Error Handling

All endpoints follow standard HTTP status codes:

Code	Meaning	Example
200	Success	Request completed successfully
400	Bad Request	Missing required fields
404	Not Found	Conversation/task not found
500	Internal Error	Server error

Error Response Format

{
  "statusCode": 400,
  "message": "Error description",
  "error": "Bad Request"
}

Rate Limiting

Consider implementing rate limiting for production:

import { ThrottlerModule } from '@nestjs/throttler';

@Module({
  imports: [
    ThrottlerModule.forRoot({
      ttl: 60,
      limit: 100
    })
  ]
})

Next Steps

Implement Webhooks for async event handling
Secure with Authentication
Monitor with Logging & Observability

Base URL​

Authentication​

Endpoints​

1. Send System Message​

Request Body​

Supported Message Types​

Example Request​

Response​

Error Responses​

2. Send Custom Message​

Request Body​

Message Envelope Types​

Example Request​

Response​

3. Get Conversation History​

URL Parameters​

Example Request​

Response​

4. Link Verification ID​

Request Body​

Example Request​

Response​

Use Case​

5. Update Conversation State​

URL Parameters​

Request Body​

Example Request​

Response​

6. Get Conversation Details​

URL Parameters​

Example Request​

Response​

Integration Examples​

Python (Webserver)​

Node.js (Webserver)​

PHP (Webserver)​

Error Handling​

Error Response Format​

Rate Limiting​

Next Steps​

Base URL

Authentication

Endpoints

1. Send System Message

Request Body

Supported Message Types

Example Request

Response

Error Responses

2. Send Custom Message

Request Body

Message Envelope Types

Example Request

Response

3. Get Conversation History

URL Parameters

Example Request

Response

4. Link Verification ID

Request Body

Example Request

Response

Use Case

5. Update Conversation State

URL Parameters

Request Body

Example Request

Response

6. Get Conversation Details

URL Parameters

Example Request

Response

Integration Examples

Python (Webserver)

Node.js (Webserver)

PHP (Webserver)

Error Handling

Error Response Format

Rate Limiting

Next Steps