Webhooks

In this update, ChatVolt Agents have two new functionalities available via the WebHook tab located at Agents > Select Agent > Settings > WebHook. These features allow agents to fetch additional external user information and to send real-time notifications for each conversation processed.

​

Fetch External User Information

This feature allows the agent to retrieve additional user details from an external source, which will then be displayed in the Inbox.

Configuration:

• URL: Enter the external URL that will be used to fetch user information.
• Header (Optional): Provide an optional header for authentication, if required.

When enabled, the agent will call the configured URL to obtain extra user data that enriches the conversation details in the Inbox.

​

WebHook Event Types

The WebHook now supports a range of event types defined by the WebhookEventType enum. These events indicate the type of conversation activity that triggered the webhook notification. The supported event types are:

• USER_MESSAGE_RECEIVED
  Triggered when only the user’s message is received (AI is disabled).

• AGENT_MESSAGE_SENDED
  Triggered when an agent sends a message via supported channels (via Inbox).

• AGENT_USER_MESSAGE
  The default event when a user sends a message and the agent responds.

• AGENT_MESSAGE_BLOCKED
  Triggered when an agent’s message is blocked (e.g., Instagram or WhatsApp outside the 24-hour window).

• AGENT_MESSAGE_NOTED
  Triggered when an agent’s message is logged as a note (e.g., unsupported channels such as API or Dashboard).

• GROUP_MESSAGE_RECEIVED
  Triggered when a group message is received and the agent is not mentioned (ZAPI).

​

Outbound WebHook

The Outbound Webhook functionality enables real-time notifications for every interaction processed by the agent. With this feature, a JSON payload is sent to a specified external URL whenever a conversation event occurs. Note that the payload attributes are conditionally included based on the event type.

Configuration:

• URL: Enter the external URL where the notification will be sent.
• Header (Optional): Provide an optional header for authentication if required.

​

Payload Attributes

The JSON payload sent via the Outbound Webhook includes the following attributes:

{
  "eventType": string,            
  "conversationId": string,
  "messageId": string,
  "agentId": string,
  "agentName": string,
  "channel": string,
  "conversationStatus": string,
  "conversationPriority": string,
  "isAiEnabled": boolean,
  "assignee": string,
  "groupId": string,              
  "groupName": string,           
  "userName": string,
  "userEmail": string,
  "userPhoneNumber": string,
  "summary": string,
  "userMessage": string,
  "agentResponse": string
}

Conditional Inclusion:

• The attributes groupId and groupName are only sent if the event type indicates a group-related event (e.g., GROUP_MESSAGE_RECEIVED).
• The eventType attribute specifies the type of event and will always be included to clarify which event triggered the payload.

Every time the agent processes a conversation, this JSON payload is sent to the configured URL, providing detailed information about the conversation, the user, and the agent’s response. The conditional inclusion of certain attributes helps tailor the payload to the specific context of the event.

​

Configuration Steps

1. Navigate to WebHook Settings:
   Go to Agents > Select Agent > Settings > WebHook.

2. Configure URL and Header:

   • Insert the desired URL for the functionality.
   • Optionally, add an authentication header if needed.

3. Save Your Changes:
   Confirm and save the configuration to activate the webhook.

​

Best Practices

• Verify URLs: Ensure that the provided URLs are correct and accessible.
• Secure Endpoints: Use authentication headers to secure data transmission.
• Monitor Notifications: Regularly check your logs to ensure that webhook notifications are delivered as expected.

Need Help? Contact our support team for assistance with configuring WebHooks.