Webhook column definitions

After setting up a Custom Webhook, you will receive the payload from your endpoints. Here are the definitions for each column

chat_id

When the message comes from a individual message, the phone numbers of both parties will be displayed as the chat ID,  xxxxxxxxxxx_xxxxxxxx@c.us.
If the message comes from a group message, the WhatsApp group chat ID, 120363041306185221@g.us, will be displayed.

chat_type

Indicate whether it is an individual chat or a group chat.

chat_title

The display name of the chat. In a 1:1 chat, it will be the saved name of the contact or the phone number of the contact. In a group chat, the chat title will be the name of the group.

sender.phone / sender.wa_name

If the message direction is "sent," the contact field will be you; if the message direction is "received," the contact field will be your client.

These fields represent the sender's phone number and WhatsApp name.

participants.phone / participants.wa_name

This column lists ALL the participants in this chat, along with their phone numbers and WhatsApp names, including the current Cooby user.

user_phone

This field indicate the current logged-in Cooby user's phone number.

user_email

This field indicate the current logged-in Cooby user's email.

direction

This column indicates the direction of the message in reference to the Cooby user.

message.id

Unique ID numbers allow you to identify each message.​

message.type

Due to WhatsApp limitations, any image type (.png, .jpg) will only display as the image file type, and the same limitation applies to video and other document types by default.

However, for files in .pdf, .csv, or .doc format, the original file type will be displayed in the payload. For other document types, it will remain as document.

message.text

This column contains the message content.

Only chat, image, video, and document message types have text in the form of message text; other types will not have a text field

message.file_name

For pdf, csv, doc, and other document types, the original file name will be displayed.
For image, video, audio, and stickers, the file name will be displayed as Cooby {{ message_type }} {{ date }} at {{ time }}

message.file_url

We will show a url link for you to download the file.

Cooby only support multimedia files up to 15 MB

message.caption

If an attachment has caption, the text will be displayed in both message.text and message.caption. If there is only an attachment without text, both message.text and message.caption will be an empty string.

message.is_error / message.error_code / message.error_messages

Below are the message error codes and their corresponding error messages supported in this update:

message.error_code        message.error_message
"file_size_out_of_limit": "[File size out of limit. Max file size supported by Cooby is 15MB.]",
"file_not_found":         "[File not found.]",
"file_expired":           "[File has expired.]",
"file_unsupported":       "[File type unsupported.]",
"invalid_file_type":      "[Invalid file type.]",
"unknown_error":          "[Unknown error.]",

timestamp

This column displays the UTC date and time when the message was sent.

Payload example

{
  chat_id: "447441369136_447441368384@c.us";
  chat_type: "individual";
  chat_title: "Sarah Brown";
  user_phone: "447441368384";
  user_email: "support@cooby.co";
  direction: "sent";
  message: {
    id: "3EB093D273669B3BE3D2";
    type: "chat";
    text: "Hi, welcome to Cooby!";
    file_name: "Cooby Image 2023-07-12 at 11.13.32 AM";
    file_url: "https://api.cooby.co/v2/files/xxxxx";
    caption: "Hi, welcome to Cooby!";
    is_error: false;
    error_code: null;
    error_message: null;
  };
  timestamp: "1628843453";
  participants: [
   {
    phone: "447441369136";
    wa_name: "Sarah Brown";
   },
   { 
    phone: "447441368384", 
    wa_name: "Cooby" 
   } 
  ],
  sender: {
    phone: "447441368384";
    wa_name: "Cooby";
  };
}

We hope this document helps you better understand how Cooby works. For any concerns or questions regarding your Custom Webhook integration, kindly email us at support@cooby.co 💜

Updated on: 29/05/2025