Create Conversation

Overview

Creates a new conversation under your business. Optionally link an existing customer and include an opening message from the agent. The conversation is associated with your business’s default channel.

Request

Method: POST URL: /api/v1/conversations/

Headers

Header	Value
Authorization	Bearer
Content-Type	application/json

Body parameters

string (UUID)

required

The UUID of your business. Must match the business associated with your account.

string (UUID)

UUID of an existing customer to associate with this conversation. Optional — leave unset if the customer is unknown at creation time.

string

An optional opening message from the agent. If provided, a message record is created with sender_type: "agent".

Response

Returns the newly created conversation object.

string (UUID)

Unique identifier for the conversation.

string (UUID)

The business this conversation belongs to.

string (UUID) | null

The associated customer, or null if not linked.

string (UUID) | null

The assigned agent, or null if unassigned.

string

Set to "open" on creation.

string

The channel type derived from the resolved channel record.

string (UUID) | null

The channel this conversation is linked to.

string (ISO 8601)

Timestamp when the conversation was created.

string (ISO 8601)

Timestamp when the conversation was last updated.

string (ISO 8601) | null

Timestamp of the first agent response. Populated immediately if initial_message is provided.

object | null

Embedded customer object if a customer_id was provided.

array

Array of messages. Contains the initial message if one was provided.

Example

curl -X POST https://api.pingback.live/api/v1/conversations/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "business_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "customer_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "initial_message": "Hi! How can I help you today?"
  }'

const response = await fetch('https://api.pingback.live/api/v1/conversations/', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    business_id: 'b2c3d4e5-f6a7-8901-bcde-f12345678901',
    customer_id: 'd4e5f6a7-b8c9-0123-defa-234567890123',
    initial_message: 'Hi! How can I help you today?',
  }),
});
const conversation = await response.json();

Response example

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "business_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "customer_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "assignee_id": null,
  "status": "open",
  "channel_type": "widget",
  "channel_id": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "created_at": "2024-03-01T09:00:00Z",
  "updated_at": "2024-03-01T09:00:00Z",
  "first_response_at": null,
  "customer": {
    "id": 42,
    "business_id": 7,
    "name": "Alex Johnson",
    "email": "alex@example.com",
    "phone": null,
    "external_id": null,
    "created_at": "2024-02-20T08:00:00Z"
  },
  "messages": [
    {
      "id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
      "conversation_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "sender_type": "agent",
      "sender_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "content": "Hi! How can I help you today?",
      "attachments": [],
      "created_at": "2024-03-01T09:00:00Z"
    }
  ]
}

Errors

Status	Meaning
400	Invalid channel — the `channel_id` does not exist or does not belong to your business
401	Unauthorized — missing or invalid Bearer token
422	Validation error — missing required fields

Authentication

Conversations

Channels & Widget

Team

Knowledge Base

Analytics

Create Conversation

Overview

Request

Headers

Body parameters

Response

Example

Response example

Errors

​Overview

​Request

​Headers

​Body parameters

​Response

​Example

​Response example

​Errors

Overview

Request

Headers

Body parameters

Response

Example

Response example

Errors