This article explains how to embed the Wazzup chat window into your CRM and set up event-driven updates for the Deals dropdown.

Deals dropdown — a tool in the chat window that lets users:

• View a list of open and closed deals associated with the contact where they are the responsible party, and navigate directly to those deals in the CRM;
• Quickly jump to the deal creation page in the CRM.

We recommend using webhooks to manage the Deals dropdown. If webhooks aren't an option, you can use events instead.

Currently, it is not possible to create a Telegram dialog via the Chat Window API using a phone number. To create a Telegram chat, use either the Send Message method or a username. Once the chat is created, you will receive a chat id, which can then be used to open MAX and Telegram dialogs in the iframe.

How to Embed the Wazzup Chat Window into Your CRM

POST /v2/iframe-links/chats
│
├── user
│ └── id *
├── author_name
├── scope *
├── chats[]
│ ├── contact_name
│ ├── chat_type *
│ ├── chat_id *
│ └── username *
├── active_chat
│ ├── channel_id
│ ├── chat_type *
│ ├── chat_id *
│ └── username *
├── use_events
│ ├── deals
│ └── messages
└── client_type

user (object)

chats (object)

active_chat (object)

use_events (object)

If a contact with the specified chat_type and chat_id does not exist in Wazzup, it will be created when opened from a CRM contact record. The contact's name will be set to the value provided in contact_name, or to the id if contact_name is not supplied.

Example request for opening the iframe within a contact or deal record

{
"user_id": "crm-user-id-123",
"author_name": "John Smith",
"scope": "card",
"chats": [
{
"contact_name": "Anthony Stone",
"chat_type": "whatsapp",
"chat_id": "37111234567"
},
{
"contact_name": "Anthony Stone",
"chat_type": "telegram",
"username": "my_tg_user"
},
{
"contact_name": "Anthony Stone",
"chat_type": "telegram",
"chat_id": "1670185"
}
],
"active_chat": {
"channel_id": "string",
"chat_type": "whatsapp",
"chat_id": "37111234567"
},
"use_events": {
"deals": false,
"messages": false
}
}

Example of a minimal request to open the iframe with all user chats

{
"user_id": "crm-user-1",
"scope": "global"
}

Example request for creating a Telegram chat using a username

{
"user": {
"id": "crm-user-id-123",
"name": "John Smith"
},
"scope": "card",
"filter": [
{
"chatType": "telegram",
"username": "best_client"
}]
}

Successful response

200

The response returns a JSON object containing the URL for opening the chat window.

{
"data": {
"link": "https://app.wazzup24.com/1234-1234/chat/telegram/1670185301/123?token=token"
},
"meta": {
"timestamp": 1764849838
}
}

If you are opening the URL in an iframe, include the allow="microphone *; clipboard-write *" attribute in the iframe tag.

The microphone permission is required to record voice messages from the chat window. If omitted, users won't be able to record voice messages — clicking the microphone will simply trigger an error.

The clipboard-write permission is required for copy‑to‑clipboard functionality within the iframe — for example, allowing users to copy an error code from a notification with a single click.

<iframe src="link" allow="microphone *; clipboard-write *" ></iframe>

Errors

Error response parameters

Error example

{
"code": "VALIDATION_FAILED",
"title": "Validation Failed",
"status": 400,
"detail": "One or more fields did not pass validation.",
"instance": "/v2/iframe-links/chats",
"method": "POST",
"errors": [
"user_id should not be empty",
"scope must be a valid enum value"
]
}

400

Possible Error Codes for 400 Status

401

Possible Error Codes for 401 status

403

Possible Error Codes for 403 status

500

Possible Error Codes for 500 status

Configuring the Deals Dropdown to Respond to Events

Events notify you when you need to:

• Create a new deal
• Display a record the user wants to open
• Create a new contact

The user clicks + in the Deals dropdown to create a deal

What this means: A new deal needs to be created using the parameters provided by the iframe.

Event name: WZ_CREATE_ENTITY

What it contains:

{body}
├── type
└── data
    ├── chatType
    ├── chatId
    ├── channelId
    ├── userId
    └── integrationId

data (object)

Event example:

{
type: 'WZ_CREATE_ENTITY',
data: {
chatType: whatsapp,
chatId: 37198887766,
channelId: c16tc1c-9f20-4rda-46jd-q92ty4j6s36888,
userId: test_id,
integrationId: 608df5ye-45hj-j6k7-l77k-qe5t88j4h1222
}
}

After creating a deal, you need to send the new deal data from your CRM back to Wazzup.

The user opens a deal, contact, or other record from the Deals dropdown.

What this means: The user needs to view a deal, contact, or other record using the parameters provided by the iframe.

Event name: WZ_OPEN_ENTITY

What it contains:

WZ_OPEN_ENTITY
├── type
└── data
    ├── chatType
    ├── chatId
    ├── channelId
    ├── userId
    ├── integrationId
    └── entity
        ├── closed
        ├── id
        ├── link
        ├── name
        └── responsibleUserName

data (object)

entity (object)

Event example:

{
type: 'WZ_OPEN_ENTITY',
data: {
chatType: whatsapp,
chatId: 37198887766,
channelId: c16tc1c-9f20-4rda-46jd-q92ty4j6s36888,
userId: test_id,
integrationId: 608df5ye-45hj-j6k7-l77k-qe5t88j4h1222,
entity: {
closed: false,
id: clientId3,
link: #,
name: TestDeal,
responsibleUserName: TestUser
}
}
}