2BeBot Webhook Endpoint Documentation

Overview

The 2BeBot webhook endpoint is designed to receive structured payloads from 2BeBot events and send them to configured external webhook URLs. This documentation outlines the expected payload structure and behavior for customers integrating with the webhook.

Payload Structure

Incoming Message Payload

When a message is received, the webhook sends the following payload:

{
  "type": "text | image | video | document | audio",
  "message_id": "string",
  "message": "string | null",
  "name": "string | null",
  "phone_number": "string",
  "url": "string | null",
  "channel_id": "number",
  "company_id": "number",
  "contact": {
    "id": "number",
    "company_id": "number",
    "channel_id": "number",
    "first_name": "string | null",
    "last_name": "string | null",
    "phone_number": "string | null",
    "email": "string | null",
    "contact_tag": {
      "tag_id": "number",
      "contact_tags": {
        "name": "string"
      }
    },
    "contacts_meta": {
      "meta_key": "string",
      "meta_value": "string"
    }
  },
  "conversation": {
    "id": "number",
    "company_id": "number",
    "contact_id": "number",
    "department_id": "number | null",
    "channel_type": "string",
    "channel_id": "number",
    "user_id": "number | null",
    "status": "string",
    "last_message": "string | null",
    "unread_count": "number",
    "started_at": "string | null",
    "ended_at": "string | null",
    "metadata": "object | null",
    "reason": "string | null",
    "goal_id": "number | null",
    "created_at": "string",
    "updated_at": "string"
  }
}

Field Descriptions

• type: The type of message (e.g., text, image, video, document, audio).

• message_id: Unique identifier for the message.

• message: The text content of the message (if applicable).

• name: The name of the sender (if available).

• phone_number: The phone number of the sender.

• url: URL of the media attachment (if applicable).

• channel_id: Identifier for the channel associated with the message.

• company_id: Identifier for the company associated with the channel.

• contact: Object containing contact details.

- id: Unique identifier for the contact.

- company_id: Identifier for the company associated with the contact.

- channel_id: Identifier for the channel associated with the contact.

- first_name: First name of the contact (if available).

- last_name: Last name of the contact (if available).

- phone_number: Phone number of the contact (if available).

- email: Email address of the contact (if available).

- contact_tag: Object containing tag information for the contact.

- tag_id: Unique identifier for the tag.

- contact_tags: Object containing tag name.

- name: Name of the tag.

- contacts_meta: Object containing metadata for the contact.

- meta_key: Key for the metadata.

- meta_value: Value for the metadata.

• conversation: Object containing conversation details.

- id: Unique identifier for the conversation.

- company_id: Identifier for the company associated with the conversation.

- contact_id: Identifier for the contact associated with the conversation.

- department_id: Identifier for the department associated with the conversation (if available).

- channel_type: Type of channel used for the conversation (e.g., WhatsApp, Messenger).

- channel_id: Identifier for the channel associated with the conversation.

- user_id: Identifier for the user associated with the conversation (if available).

- status: Current status of the conversation (e.g., open, closed).

- last_message: Content of the last message in the conversation (if available).

- unread_count: Number of unread messages in the conversation.

- started_at: Timestamp when the conversation was started (if available).

- ended_at: Timestamp when the conversation was ended (if available).

- metadata: Additional metadata associated with the conversation (if available).

- reason: Reason for the conversation status (if available).

- goal_id: Identifier for the goal associated with the conversation (if available).

- created_at: Timestamp when the conversation was created.

- updated_at: Timestamp when the conversation was last updated.

Message Status Update Payload

When a message status is updated (e.g., delivered, read), the webhook sends the following payload:

{
  "message_id": "string",
  "status": "string",
  "timestamp": "number",
  "channel_id": "number",
  "company_id": "number"
}

Field Descriptions

• message_id: Unique identifier for the message.

• status: The status of the message (e.g., delivered, read).

• timestamp: Unix timestamp of the status update.

• channel_id: Identifier for the channel associated with the message.

• company_id: Identifier for the company associated with the channel.

Behavior

Retry Mechanism

The webhook implements a retry mechanism for failed requests:

• Retry Count: Up to 10 retries.

• Retry Delay: Exponential backoff starting at 7 seconds.

Logging

All webhook requests and responses are logged in the database for auditing purposes:

• Request Body: The payload sent to the external webhook.

• Response Code: HTTP status code returned by the external webhook.

• Response Body: The response content returned by the external webhook.

Integration

Customers should ensure their endpoint is capable of:

1. Receiving POST requests with the above payload structures.

2. Responding with appropriate HTTP status codes (e.g., 200 for success).

3. Handling retries for transient errors.

Example

Incoming Message Example

{
  "type": "text",
  "message_id": "abc123",
  "message": "Hello, world!",
  "name": "John Doe",
  "phone_number": "1234567890",
  "url": null,
  "channel_id": 1,
  "company_id": 101,
  "contact": {
    "id": 1,
    "company_id": 101,
    "channel_id": 1,
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "1234567890",
    "email": "john.doe@example.com",
    "contact_tag":{
      "tag_id": 1,
      "contact_tags":{"name": "Customer"}
    },
    "contacts_meta":{
      "meta_key":"address",
      "meta_value":"123 Main St, Anytown, USA"
    }
  },
  "conversation": {
    "id": 1,
    "company_id": 101,
    "contact_id": 1,
    "department_id": 1,
    "channel_type": "WhatsApp",
    "channel_id": 1,
    "user_id": 1,
    "status": "open",
    "last_message": "Hello, world!",
    "unread_count": 0,
    "started_at": 1625078400,
    "ended_at": null,
    "metadata": {
      "key": "value"
    },
    "reason": "User initiated",
    "goal_id": 1,
    "created_at": 1625078400,
    "updated_at": 1625078400
  },
}

Message Status Update Example

{
  "message_id": "abc123",
  "status": "delivered",
  "timestamp": 1625078400,
  "channel_id": 1,
  "company_id": 101
}

Contact

For further assistance, please contact our support team.