Articles on: Webhook Integration

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

Was this article helpful?

Share your feedback

Cancel

Thank you!