API Documentation

Webhook API Guide

This page helps you setting up your agent webhooks.

The Webhook API guide allows you to set-up webhooks to receive a POST request when an event is triggered.

Payload Structure

Key	Type	Description
eventType	string	event type (eg. lead.submit)
agentId	string	Agent ID
payload	Object	Payload of the event

{
  "eventType": "string",  // event type (eg. lead.submit)
  "agentId": "string",  // Agent ID
  "payload": {           // Payload of the event
    // ... event specific data
  }
}

Event Types

These are the list of events supported in webhooks.

lead.submit

When a customer submits their info (Name, Email, and Phone) to your agent.

{
  "conversationId": "string",
  "customerEmail": "string",
  "customerName": "string",
  "customerPhone": "string"
}

Channel Integrations

Webhooks are used to receive events from all messaging channels your agent is connected to. Each channel delivers events to the same webhook URL with a channel field so you can route them appropriately.

channel: "whatsapp"

Received when a user sends a message to your WhatsApp business number connected to the agent.

{
  "eventType": "message.received",
  "channel": "whatsapp",
  "agentId": "agent_abc123",
  "payload": {
    "from": "+1234567890",
    "message": "Hello, I need help with my order",
    "conversationId": "conv_xyz"
  }
}

channel: "telegram"

Received when a user messages your Telegram bot linked to the agent.

{
  "eventType": "message.received",
  "channel": "telegram",
  "agentId": "agent_abc123",
  "payload": {
    "chatId": 123456789,
    "username": "john_doe",
    "message": "What are your opening hours?",
    "conversationId": "conv_xyz"
  }
}

Facebook Messenger

channel: "facebook"

Received when a user sends a message to your Facebook Page linked to the agent.

{
  "eventType": "message.received",
  "channel": "facebook",
  "agentId": "agent_abc123",
  "payload": {
    "senderId": "fb_user_123",
    "pageId": "fb_page_456",
    "message": "Is this product still available?",
    "conversationId": "conv_xyz"
  }
}

Instagram

channel: "instagram"

Received when a user sends a DM to your Instagram account linked to the agent.

{
  "eventType": "message.received",
  "channel": "instagram",
  "agentId": "agent_abc123",
  "payload": {
    "senderId": "ig_user_789",
    "message": "Do you ship internationally?",
    "conversationId": "conv_xyz"
  }
}

Email

channel: "email"

Received when an inbound email arrives at your agent's connected inbox.

{
  "eventType": "message.received",
  "channel": "email",
  "agentId": "agent_abc123",
  "payload": {
    "from": "customer@example.com",
    "subject": "Order inquiry",
    "message": "I placed an order yesterday and have not received a confirmation.",
    "conversationId": "conv_xyz"
  }
}

Web Chat Widget

channel: "web"

Received when a visitor sends a message through the embedded chat widget on your website.

{
  "eventType": "message.received",
  "channel": "web",
  "agentId": "agent_abc123",
  "payload": {
    "sessionId": "session_abc",
    "message": "Hi, I need help!",
    "conversationId": "conv_xyz",
    "pageUrl": "https://yoursite.com/pricing"
  }
}

Tip: Use the channel field in the webhook payload to route incoming events to different handlers in your backend.

Receiving the Webhook Request

You can receive the payload by accessing the body same as any request.

It is recommended to check the request header x-chatzuri-signature for securing your endpoint from spam.

You can achieve this by using SHA-1 (Secure Hash Algorithm 1) function to generate a signature for the request and compare it with x-chatzuri-signature found in the request headers. If they are identical then the request is from Chatzuri.

Example Request

import crypto from 'crypto'
import { Request, Response } from 'express'

export async function webhookHandler(req: Request, res: Response) {
  if (req.method === 'POST') {
    const { SECRET_KEY } = process.env
    
    const receivedJson = req.body
    const rawBody = Buffer.from(JSON.stringify(receivedJson))
    const bodySignature = sha1(rawBody, SECRET_KEY)

    if (bodySignature !== req.headers['x-chatzuri-signature']) {
      return res.status(400).json({ message: "Signature didn't match" })
    }

    console.log('Received:', receivedJson)
    
    res.status(200).json({ status: "accepted" })
  } else {
    res.setHeader('Allow', 'POST')
    res.status(405).end('Method Not Allowed')
  }
}

function sha1(data: Buffer, secret: string): string {
  return crypto.createHmac('sha1', secret).update(data).digest('hex')
}

Respond to the Event Webhook

Return a JSON object with the following structure to indicate your endpoint has received the event webhook:

{
  "status": "accepted"
}

Error Handling

If there are any errors during the API request, appropriate HTTP status codes will be returned along with error messages in the response body.

That's it! You should now be able to retrieve list of agent's from your account using our API.

Remember to handle errors gracefully in your application

Home: API Documentation