Skip to main content

​
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

HeaderValue
AuthorizationBearer
Content-Typeapplication/json

​
Body parameters

​
business_id
string (UUID)
required
The UUID of your business. Must match the business associated with your account.
​
customer_id
string (UUID)
UUID of an existing customer to associate with this conversation. Optional — leave unset if the customer is unknown at creation time.
​
initial_message
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.
​
id
string (UUID)
Unique identifier for the conversation.
​
business_id
string (UUID)
The business this conversation belongs to.
​
customer_id
string (UUID) | null
The associated customer, or null if not linked.
​
assignee_id
string (UUID) | null
The assigned agent, or null if unassigned.
​
status
string
Set to "open" on creation.
​
channel_type
string
The channel type derived from the resolved channel record.
​
channel_id
string (UUID) | null
The channel this conversation is linked to.
​
created_at
string (ISO 8601)
Timestamp when the conversation was created.
​
updated_at
string (ISO 8601)
Timestamp when the conversation was last updated.
​
first_response_at
string (ISO 8601) | null
Timestamp of the first agent response. Populated immediately if initial_message is provided.
​
customer
object | null
Embedded customer object if a customer_id was provided.
​
messages
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?"
  }'

​
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

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