Webhook API

The Webhook API lets you:

• receive events from VivoChat on your server;
• pass information from your system to VivoChat.

VivoChat sends HTTP POST requests to the specified URLs.

Each webhook is configured separately in the VivoChat interface.

chat_accepted

chat_accepted lets you:

• update customer information in the “Contacts” section;
• show additional data in the current dialog.

chat_accepted is sent when an operator accepts a dialog.

How it works

After an operator accepts a dialog, VivoChat sends an HTTP POST request to your server.

The request includes information about the dialog, the channel, and the userToken, if it was set via setUserToken() (otherwise null).

In the response, your server can return:

• contactInfo — updates customer information in the “Contacts” section;
• customData — displayed in the “Additional” section of the current dialog.

In contactInfo you can pass limited customer data using:

• “name” - for the customer’s name, string;
• “phone” - for the phone number, string;
• “email” - “[email protected]”.

In customData the types of data you can pass are not limited.

Webhook configuration

The webhook is configured separately for each channel in the VivoChat interface:

Management → Communication channels → [channel] → Webhooks integration

You can use the same URL for multiple channels.

Request format

{
  "type": "chat_accepted",
  "userToken": "USER_TOKEN",
  "chatId": "2c9c6f9e-2f47-4b85-9a59-3a59e2d87f9d", // Unique dialog identifier
  "channel": {
    "type": "widget",
    "id": "1CafijNcdgYtDhS3vg9b1V" // Unique channel identifier
  }
}

Request fields

Field	Type	Description
type	string	Event type. Always chat_accepted
userToken	string | null	Token from setUserToken()
chatId	string	Dialog identifier
channel	object	Channel information

Response example

{
    "result": "ok",
    "customData": [
        { "title": "Order", "content": "123456789" },
        { "title": "Tariff", "content": "Premium" }

    ],
    "contactInfo": {
        "name": "John Smith",
        "phone": "+14084987855",
        "email": "[email protected]"
    }
}

In this example:

• contactInfo updates the customer’s data and displays it in the “Contacts” section;
• customData displays the order number and tariff plan in the “Additional” section of the current dialog.

Response fields

Field	Type	Description
result	string	Required response field
contactInfo	object	Updates customer information
customData	array	Displayed only in the current dialog

Important

• the server must respond with HTTP code 200;
• the event is not retried automatically on error or timeout;
• userToken will be null if setUserToken() was not used.

chat_finished

chat_finished is called after a dialog ends.

Use chat_finished if you need to:

• save the dialog history in your system;
• analyze customer conversations.

How it works

After a dialog ends, VivoChat sends an HTTP POST request to your server.

The event is triggered if the dialog is:

• finished;
• rejected;
• blocked.

The request includes complete information about the finished dialog:

• customer;
• channel;
• current operator;
• list of operators;
• messages;
• visits;
• dialog rating;
• intents;
• dialog creation time;
• dialog completion time.

The structure of the POST request is described in the “chat_finished data structure” section.

Webhook configuration

The webhook is configured separately for each channel in the VivoChat interface:

Management → Communication channels → [channel] → Webhooks integration

You can use the same URL for multiple channels.

Response format

The server must respond with HTTP 200.

Minimal successful response:

{
  "result": "ok"
}

Response fields

Field	Type	Description
result	string	Required response field

Important

• the server must respond with HTTP code 200;
• the event is not resent on error or timeout;
• the order in which events are received is not guaranteed;
• it is recommended to ignore repeated processing of the same chatId;
• some fields may arrive as null.

chat_finished data structure

The chat_finished event contains complete information about the finished dialog.

All timestamp fields are passed as Unix timestamps in seconds.

chat_finished POST request example

{
  "type": "chat_finished",
  "chatId": "2c9c6f9e-2f47-4b85-9a59-3a59e2d87f9d",
  "channel": {
    "id": "1CafijNcdgYtDhS3vg9b1V",
    "name": "Website Chat",
    "type": "widget"
  },
  "client": {
    "id": "4de4c8b4-2f5d-48e4-85d5-2fdf1a2b7c44",
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+14084987855",
    "externalId": "customer_123"
  },
  "operator": {
    "id": "e11db1c1-fd5f-4d77-aed8-c0b4e5f8d4f1",
    "email": "[email protected]",
    "accepted": 1717420050
  },
  "operators": [
    {
      "id": "e11db1c1-fd5f-4d77-aed8-c0b4e5f8d4f1",
      "email": "[email protected]",
      "accepted": 1717420050
    }
  ],
  "messages": [
    {
      "type": "message",
      "sender": "client",
      "operatorId": null,
      "sent": 1717420060,
      "message": "Hello",
      "generated": false,
      "attachment": null
    },
    {
      "type": "message",
      "sender": "operator",
      "operatorId": "e11db1c1-fd5f-4d77-aed8-c0b4e5f8d4f1",
      "sent": 1717420080,
      "message": "How can I help you?",
      "generated": false,
      "attachment": null
    }
  ],
  "visits": [
    {
      "referer": "https://example.com/pricing",
      "city": "San Francisco",
      "country": "United States",
      "ipAddress": "203.0.113.10",
      "organization": "Example ISP"
    }
  ],
  "rate": {
    "satisfied": true,
    "comment": "Great support",
    "timestamp": 1717420300
  },
  "intents": [
    {
      "id": "9f0d4a8f-4f3e-4c9d-9c71-5d6e9d4f5a1b",
      "name": "support_request"
    }
  ],
  "created": 1717420000,
  "completed": 1717420300
}

Main fields

Field	Type	Description
type	string	Event type. Always chat_finished
chatId	uuid	Dialog identifier
channel	Channel	Channel information
client	Client	Customer information
operator	Operator | null	Current operator
operators	Operator[]	List of dialog operators
messages	Message[] | MessageVoice[] | MessageCall[]	Message history
visits	Visit[]	Visit information
rate	Rate | null	Customer rating
intents	Intent[]	Dialog intents
created	timestamp	Dialog creation time
completed	timestamp | null	Dialog completion time

Channel

Information about the channel through which the dialog was created.

Field	Type	Description
id	uuid	Channel identifier
name	string	Channel name
type	string	Channel type: widget, email, telegram, whatsapp, instagram

Client

Customer information.

Field	Type	Description
id	uuid	Customer identifier in VivoChat
name	string	Customer name
email	string | null	Customer email
phone	string | null	Customer phone
externalId	string | null	Customer identifier in your system
telegram	ClientTelegram | null	Customer’s Telegram account
instagram	ClientInstagram | null	Customer’s Instagram account

ClientTelegram

Customer’s Telegram account.

Field	Type	Description
id	string	User ID in Telegram
chatId	string	Chat ID in Telegram
username	string | null	Customer username
firstName	string | null	Customer first name
lastName	string | null	Customer last name

ClientInstagram

Customer’s Instagram account.

Field	Type	Description
id	string	Account ID
username	string | null	Customer username

Operator

Operator information.

Field	Type	Description
id	uuid	Operator identifier
email	string	Operator email
accepted	timestamp	Dialog acceptance time

Messages

The messages[] array may contain different message types.

Type	Description
message	Text message
voice	Voice message
call	Call recording

Message

Text message.

Field	Type	Description
type	string	Always message
sender	string	client or operator
operatorId	uuid | null	Operator identifier
sent	timestamp	Sent time
message	string	Message text
generated	boolean	Message generated by AI
attachment	Image | Document | Video | null	Attachment

MessageVoice

Voice message.

Field	Type	Description
type	string	Always voice
voice	Voice	Audio recording
sender	string	client or operator
operatorId	uuid | null	Operator identifier
sent	timestamp	Sent time

Voice

Audio recording of a voice message.

Field	Type	Description
length	int	Recording duration
url	string	Audio file URL

MessageCall

Call recording.

Field	Type	Description
type	string	Always call
call	Call	Call recording
sender	string	Always operator
operatorId	uuid | null	Operator identifier
sent	timestamp	Call time

Call

Phone call recording.

Field	Type	Description
size	int	File size
url	string	Audio file URL
result	string	Call result

Attachment

The attachment field may contain an image, a document, or a video.

Image

Field	Type	Description
type	string	Always image
url	string	Image URL
originalFileName	string	File name
height	int	Image height
width	int	Image width

Document

Field	Type	Description
type	string	Always document
url	string	Document URL
originalFileName	string	File name

Video

Field	Type	Description
type	string	Always video
url	string	Video URL
originalFileName	string	File name
length	int	Video duration

Visit

Customer visit information.

Field	Type	Description
referer	string | null	Page URL
city	string	Customer city
country	string	Customer country
ipAddress	string	IP address
organization	string | null	Provider or organization

Rate

Dialog rating given by the customer.

Field	Type	Description
satisfied	boolean	Positive or negative rating
comment	string | null	Customer comment
timestamp	timestamp	Rating time

Intent

Dialog intent.

Field	Type	Description
id	uuid	Intent identifier
name	string	Intent name

client_check_token

The client_check_token event is used to verify an authorized customer.

Use client_check_token if you need to:

• link the dialog to a customer from your system;
• show the operator the customer’s name, phone, and email;
• merge the customer’s dialog history across devices and sessions.

How it works

If your site uses authorization, pass the user token via setUserToken().

When the chat is first opened, VivoChat will send an HTTP POST request with the type client_check_token to the customer verification URL.

The request includes:

• the event type;
• the userToken passed via setUserToken().

Your server must:

• verify the token;
• find the customer in your system;
• return clientId;
• return the customer’s contact data if necessary.

If the customer is found:

• VivoChat will link the dialog to the customer;
• the operator will see the customer’s contacts in the “Contacts” section;
• the dialog history will be merged across sessions.

If the customer is not found:

• return a successful response without clientId;
• the dialog will continue as anonymous.

Caching

The verification response is cached on the VivoChat side.

Reopening the chat with the same userToken does not trigger a repeated request to your server.

To re-verify, you need to pass a new token.

Configuring the verification URL

The verification URL is configured once for the entire organization:

Settings → Dialogs → Customer verification address

The URL is used for all channels of the organization.

Request format

{
  "type": "client_check_token",
  "userToken": "USER_TOKEN"
}

Request fields

Field	Type	Description
type	string	Event type. Always client_check_token
userToken	string	Token from setUserToken()

Response format

{
    "result": "ok",
    "clientId": "customer_123",
    "contactInfo": {
        "name": "John Smith",
        "phone": "+14084987855",
        "email": "[email protected]"
    }
}

Response fields

Field	Type	Description
result	string	Required response field
clientId	string | null	Permanent customer identifier in your system
contactInfo	object	Customer contact data

ContactInfo

All fields of the contactInfo object are optional.

Field	Type	Description
name	string | null	Customer name
phone	string | null	Customer phone
email	string | null	Customer email

Important

• the server must respond with HTTP code 200;
• the request is not resent on error or timeout;
• userToken is passed without any check or validation on the VivoChat side;
• the token format is defined by your system;
• if clientId is missing, the customer is considered anonymous;
• when the user logs out of their account, it is recommended to clear the token vivo_api.setUserToken(null) so that other users of the browser do not have access to the conversation;
• a detailed description of how customer verification works is provided in the corresponding “Customer verification” section.

ticket_create

ticket_create is sent when a ticket is created.

Use ticket_create if you need to:

• notify an external system about a new ticket;
• trigger automations after a ticket is created on your site or product side.

To configure it and obtain documentation, contact the VivoChat development team.

ticket_finished

ticket_finished is sent when a ticket is finished.

Use ticket_finished if you need to:

• notify an external system about a ticket being closed;
• trigger automations after a ticket is closed on your site or product side.

To configure it and obtain documentation, contact the VivoChat development team.