Agent 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.

​

Outbound Webhook & Event Types

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 specific conversation event occurs.

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.

​

Supported Event Types:

• USER_MESSAGE_RECEIVED
  • Description: Triggered when a user’s message is received and the AI is disabled for the conversation.
• AGENT_MESSAGE_SENDED
  • Description: Triggered when an agent sends a message through a supported channel (e.g., via the Inbox).
• AGENT_USER_MESSAGE
  • Description: The default event, triggered when a user sends a message and the agent successfully responds.
• AGENT_MESSAGE_FOLLOW_UP
  • Description: Triggered when an agent sends a follow-up message in a conversation.
• AGENT_MESSAGE_BLOCKED
  • Description: Triggered when an agent’s message is blocked (e.g., on Instagram or WhatsApp outside the 24-hour response window).
• AGENT_MESSAGE_NOTED
  • Description: Triggered when an agent’s message is logged as a note because it was sent via an unsupported channel (e.g., API or Dashboard).
• GROUP_MESSAGE_RECEIVED
  • Description: Triggered when a message is received in a group and the agent was not mentioned (specific to ZAPI integration).
• STEP_ENTERED
  • Description: Triggered when a conversation enters a specific step in a FluxVolt (CRM) scenario. This is configured directly within the step settings, not in the agent’s main webhook settings.

​

Payload Attributes

The JSON payload sent via the Outbound Webhook is structured based on the event type. Below is a complete list of all possible attributes. Note that not all attributes are present in every event.

{
  "eventType": "string",
  "conversationId": "string",
  "messageId": "string",
  "agentId": "string",
  "agentName": "string",
  "channel": "string",
  "conversationStatus": "string",
  "conversationPriority": "string",
  "isAiEnabled": "boolean",
  "organizationId": "string",
  "assignee": "string",
  "assigneeName": "string",
  "groupId": "string",
  "groupName": "string",
  "userName": "string",
  "userEmail": "string",
  "userPhoneNumber": "string",
  "summary": "string",
  "userMessage": "string",
  "agentResponse": "string",
  "scenarioId": "string",
  "scenarioName": "string",
  "stepId": "string",
  "stepName": "string",
  "createdAt": "string",
  "frustration": "number",
  "tags": ["string"]
}

​

Attribute Details & Conditional Inclusion:

• Core Attributes (Always Included): eventType, conversationId, agentId, agentName, channel, conversationStatus, conversationPriority, isAiEnabled, organizationId.
• messageId: Included in message-related events like USER_MESSAGE_RECEIVED, AGENT_MESSAGE_SENDED, AGENT_USER_MESSAGE, AGENT_MESSAGE_NOTED, and GROUP_MESSAGE_RECEIVED.
• userMessage: Included when a user message is part of the event (USER_MESSAGE_RECEIVED, AGENT_USER_MESSAGE, GROUP_MESSAGE_RECEIVED).
• agentResponse: Included when an agent response is part of the event (AGENT_MESSAGE_SENDED, AGENT_USER_MESSAGE, AGENT_MESSAGE_BLOCKED, AGENT_MESSAGE_NOTED).
• Group Attributes (groupId, groupName): Sent only with the GROUP_MESSAGE_RECEIVED event.
• FluxVolt Attributes (scenarioId, scenarioName, stepId, stepName): Sent only with the STEP_ENTERED event.
• Optional Attributes: Fields like assignee, assigneeName, userName, userEmail, userPhoneNumber, summary, frustration, and tags are included if the data is available for the conversation.

​

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.