> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pingback.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Conversation

> Start a new conversation on behalf of a customer.

## 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 {token}   |
| Content-Type  | application/json |

### Body parameters

<ParamField body="business_id" type="string (UUID)" required>
  The UUID of your business. Must match the business associated with your account.
</ParamField>

<ParamField body="customer_id" type="string (UUID)">
  UUID of an existing customer to associate with this conversation. Optional — leave unset if the customer is unknown at creation time.
</ParamField>

<ParamField body="initial_message" type="string">
  An optional opening message from the agent. If provided, a message record is created with `sender_type: "agent"`.
</ParamField>

## Response

Returns the newly created conversation object.

<ResponseField name="id" type="string (UUID)">
  Unique identifier for the conversation.
</ResponseField>

<ResponseField name="business_id" type="string (UUID)">
  The business this conversation belongs to.
</ResponseField>

<ResponseField name="customer_id" type="string (UUID) | null">
  The associated customer, or `null` if not linked.
</ResponseField>

<ResponseField name="assignee_id" type="string (UUID) | null">
  The assigned agent, or `null` if unassigned.
</ResponseField>

<ResponseField name="status" type="string">
  Set to `"open"` on creation.
</ResponseField>

<ResponseField name="channel_type" type="string">
  The channel type derived from the resolved channel record.
</ResponseField>

<ResponseField name="channel_id" type="string (UUID) | null">
  The channel this conversation is linked to.
</ResponseField>

<ResponseField name="created_at" type="string (ISO 8601)">
  Timestamp when the conversation was created.
</ResponseField>

<ResponseField name="updated_at" type="string (ISO 8601)">
  Timestamp when the conversation was last updated.
</ResponseField>

<ResponseField name="first_response_at" type="string (ISO 8601) | null">
  Timestamp of the first agent response. Populated immediately if `initial_message` is provided.
</ResponseField>

<ResponseField name="customer" type="object | null">
  Embedded customer object if a `customer_id` was provided.
</ResponseField>

<ResponseField name="messages" type="array">
  Array of messages. Contains the initial message if one was provided.
</ResponseField>

## Example

<CodeGroup>
  ```bash curl theme={null}
  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?"
    }'
  ```

  ```javascript JavaScript theme={null}
  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();
  ```
</CodeGroup>

### Response example

```json theme={null}
{
  "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                                            |