Chat window (iFrame)

In this article, we will tell you how to embed the Wazzup chat window into your CRM and set up the work of the “Deals” dropdown based on events.

We recommend working with the “Deals” dropdown using webhooks. And if webhooks can not be used — by events.

How to embed a Wazzup chat window into your CRM

To get the link that will open the chat window, you need to call

 POST https://api.wazzup24.com/v3/iframe
Request parameters
Parameter

Required parameters are marked with an asterisk

Type Description
user* Object The object that contains information about the user
user.id* String ID of the user who opens the chat window
user.name* String User name. Further used as the sender’s name
scope* String The context in which the window opens where:

  • “global” for the chat window with all available chats to the user,
  • “card” for the chat from the entity card.
filter Object (Array) An array of objects with chats to show. Required when scope = card
filter.chatType String Available values:

  • WhatsApp: “whatsapp”,
  • WhatsApp group chat: “whatsgroup”,
  • Viber: “viber”,
  • Instagram: “instagram”,
  • Telegram: “telegram”.
filter.username String For Telegram only.
The username of a Telegram contact, without the @ at the beginning. Can be used for Telegram if chatId is unknown
filter.phone String For Telegram only.
The phone number of a Telegram contact. Only numbers, without spaces and special characters in the format 79011112233. Can be used for Telegram if chatId is unknown
filter.chatId String Chat ID (contact’s account in messenger):

  • for “whatsapp” and “viber” — only numbers, without spaces and special characters in the format 79011112233,
  • for “instagram” — an account without “@” in the beginning,
  • for “whatsgroup” — comes in webhooks of incoming messages,
  • for “telegram” — comes in webhooks of incoming messages and in response to a request when sending an outgoing one with phone or username parameters.
filter.name String Optional parameter that contains the name of the contact
activeChat Object Chat, active on opening Iframe
activeChat.channelId String Identifier of the channel in which you want to open an active chat when you open iFrame
activeChat.chatType String  Available values:

  • WhatsApp: “whatsapp”,
  • WhatsApp group chat: “whatsgroup”,
  • Viber: “viber”,
  • Instagram: “instagram”,
  • Telegram: “telegram”.
activeChat.chatId String Chat ID (contact’s account in messenger):

  • for “whatsapp” and “viber”— only numbers, without spaces and special characters in the format 79011112233,
  • for “instagram” — an account without “@” in the beginning,
  • for “whatsgroup” — comes in webhooks of incoming messages,
  • for “telegram” — comes in webhooks of incoming messages and in response to a request when sending an outgoing one with phone or username parameters.
activeChat.username String For Telegram only.
The username of a Telegram contact, without the @ at the beginning. Can be used for Telegram if chatId is unknown
activeChat.phone String For Telegram only.
The phone number of a Telegram contact. Only numbers, without spaces and special characters in the format 79011112233. Can be used for Telegram if chatId is unknown
options Object Settings for iframe events.

Required if you decide to create contacts and deals by events.

options.clientType String CRM type. You don’t have to specify anything
options.useDealsEvents Boolean Specify “true” if you want to be notified by iframe to create or show a deal to the user.

The event comes when the user clicks on the + in the “Deals” dropdown to create a deal from our iframe, or on an entity in the “Deals” dropdown

options.useMessageEvents Boolean Specify “true” if you want to be notified by iframe to create a new contact.

The event comes when the user responds to an incoming message from our iframe

If a contact with the specified chatType and chatId is not in the Wazzup database, when you open it in the contact card of the CRM system, it will be created. The name will be used as the name, or the chatId if the former is missing.

Request example
 curl --location --request POST 'https://api.wazzup24.com/v3/iframe' \
--header 'Authorization: Bearer c8cf90554027882f912520f454468d27' \
--header 'Content-Type: application/json' \
--data-raw '
{

"user": {
"id": "222555",
"name": "User Name"
},

"scope": "card",
"filter": [

{
"chatType": "whatsapp",
"chatId": "79998887766"
}

],
"activeChat": {
"chatType": "whatsapp",
"chatId": "79998887766"
}
}
'
Response

The response will come with a json with a link to open the chat window.

If you open the link in the iframe, add the allow=”microphone *; clipboard-write *” attribute to the tag.

You need to specify “microphone” so that users can record voice messages from the chat window. If not, the user will see an error when clicking on the microphone icon to record.

Passing “clipboard-write” is necessary to make clipboard copying work properly in our iframe. For example, the user could copy the error code from the notification on the button.

 <iframe src="link" allow="microphone *; clipboard-write *"></iframe>
Response example
{
"url": "https://12345678.wazzup24.com/chat/0e812899-e25b-4a18-a3e4-d1f5890f9de7?token=${token}"
}

In case of an error, the response will receive a json containing the error property, or an http code 500.
Error response example
 { "error": { "code": "NO_SUCH_ACCOUNT" }

Events sent by iframe

This section describes how to set up the “Deals” dropdown operation in iframe by events. A recommended way to set up it is with webhooks.

Events signal the need to:

  • create a new deal,
  • show the entity the user wants to open,
  • create a new contact.

What events can be reported by an iframe

What means: you have to create a new deal with the parameters that were passed to the iframe in the event.

Name: WZ_CREATE_ENTITY

How to get: send us options.useDealsEvents: true when generating the iframe link.

What it contains:

Field Type Description
type String Event name WZ_CREATE_ENTITY
data Object  The object that contains the event data
data.chatType String Chat messenger type: whatsapp, instagram, telegram, vk, avito
data.chatId String Chat ID (contact's messenger account)
data.channelId String Channel ID
data.userId Number CRM user ID
data.integrationId String Integration ID

Example of an event:

{
  type: 'WZ_CREATE_ENTITY',
  data: {
    chatType: whatsapp,
    chatId: 79998887766,
    channelId: c16tc1c-9f20-4rda-46jd-q92ty4j6s36888,
    userId: test_id,
    integrationId: 608df5ye-45hj-j6k7-l77k-qe5t88j4h1222
  } 
}
After creating a deal, you must send data about the new deal from CRM to Wazzup.

What means: the user wants to open a deal, contact, or other entity, with the parameters passed from the iframe.

Name: WZ_OPEN_ENTITY

How to get: send us options.useDealsEvents: true when generating the iframe link.

What it contains:

Field Type Description
type String Event name WZ_CREATE_ENTITY
data Object  The object that contains the event data
data.chatType String Chat messenger type: whatsapp, instagram, telegram, vk, avito
data.chatId String Chat ID (contact's messenger account)
data.channelId String Channel ID
data.userId Number CRM user ID
data.integrationId String Integration ID
data.entity Object The object that contains the entity data
data.entity.closed Boolean Flag. Indicates whether a deal is closed or opened
data.entity.id Number Identifier of the entity which is opened by the user
data.entity.link String Link to the entity. There can be nothing
data.entity.name String Entity name
data.entity.responsibleUserName String Name of the user responsible for the entity

Example of an event:

{
  type: 'WZ_OPEN_ENTITY',
  data: {
    chatType: whatsapp,
    chatId: 79998887766,
    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
    }
  } 
}

What means: you have to create a contact with the parameters that were passed from the iframe.

The event will come every time the salesperson sends a message, not just when he writes to the customer for the first time. Therefore, the event can come when the contact has already been created in the CRM.

Name: WZ_OUTPUT_MESSAGE

How to get: send us options.useMessageEvents: true when generating the iframe link.

What it contains:

Field Type Description
type String Event name WZ_CREATE_ENTITY
data Object  The object that contains the event data
data.chatType String Chat messenger type: whatsapp, instagram, telegram, vk, avito
data.chatId String Chat ID (contact's messenger account)
data.channelId String Channel ID
data.userId Number CRM user ID
data.integrationId String Integration ID
data.messageId String Sent Message ID
data.name String Name of a contact in messenger, social networks
data.username
String Contact's @username in Telegram
data.telephone String Contact's phone number in Telegram

Example of an event:

{
  type: 'WZ_OUTPUT_MESSAGE',
  data: {
    chatType: whatsapp,
    chatId: 79998887766,
    channelId: c16tc1c-9f20-4rda-46jd-q92ty4j6s36888,
    userId: test_id,
    integrationId: 608df5ye-45hj-j6k7-l77k-qe5t88j4h1222,
    messageId: 7886о490-49df-8hj3-3jkj-wes4xc54fwd
  } 
}
After creating a contact, you must send data about the contact from CRM to Wazzup.

We made an HTML page that serves as an example of how you can catch iframe events. How to use:

  1. Generate a link to the iframe using the API method.
  2. Insert that link into the input field of the HTML page.
  3. The chat interface will be displayed. You will be able to tap on the necessary buttons to trigger an event — the data that came in this event will appear above the iframe.