> For the complete documentation index, see [llms.txt](https://documentation.proto.cx/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.proto.cx/docs/developers/apis/conversations-api.md).

# Conversations API

Create tickets and livechats, send messages and internal notes, update status, and read conversation history.

***

### [**Create ticket**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/create_conversation_v1_conversations__subcompany_id__create_ticket_post)

Creates a ticket conversation for an existing customer. Returns the new conversation's ID.

{% code title="URL" overflow="wrap" %}

```
POST https://v3-api.proto.cx/api/platform/v1/conversations/{subcompany_id}/create-ticket
```

{% endcode %}

{% code title="Body" overflow="wrap" %}

```
{
  "subject": "string" (required),
  "customer_id": "string",
  "external_customer_id": "string",
  "gateway_profile_id": "string",
  "provided_unique_id": "string"
}
```

{% endcode %}

{% hint style="warning" %}
One of **customer\_id**, **external\_customer\_id**, **gateway\_profile\_id**, or **provided\_unique\_id** must be provided to identify the customer.
{% endhint %}

{% code title="Returns" overflow="wrap" %}

```
{
  "id": "string"
}
```

{% endcode %}

***

### [**Create ticket action**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/create_ticket_action_v1_conversations__subcompany_id___bot_id___channel_id__create_ticket_action_post)

Creates a ticket on behalf of an AI agent on a specific channel, as the [Create ticket](/docs/modules/ai-agents/workflows-and-actions/create-ticket.md) workflow action does. Accepts the full ticket payload: customer details, description, tags, assignee or assigned teams, custom fields, and the email templates used to notify the customer and assignee.

{% code title="URL" overflow="wrap" %}

```
POST https://v3-api.proto.cx/api/platform/v1/conversations/{subcompany_id}/{bot_id}/{channel_id}/create-ticket-action
```

{% endcode %}

{% code title="Body" overflow="wrap" %}

```
{
  "subject": "string" (required),
  "customer_full_name": "string" (required),
  "customer_email": "string" (required),
  "is_custom_subject": "boolean",
  "customer_phone": "string",
  "description": "string",
  "applied_tags": "array",
  "applied_tag_groups": "array",
  "customer_email_template_id": "string",
  "assignee_email_template_id": "string",
  "assignee_user_id": "string",
  "assigned_team_ids": "array",
  "from_email_sender_id": "string",
  "custom_fields": "array",
  "attachment_ids": "array",
  "linked_conversation_id": "string",
  "created_at": "string"
}
```

{% endcode %}

***

### [**Get conversation details**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/get_conversation_details_external_v1_conversations__subcompany_id___conversation_id__get_conversation_details_get)

Returns the full record for one conversation: identifiers, channel and customer profile, creator, current and historical agent and team assignments, status, tags, and custom field values.

{% code title="URL" overflow="wrap" %}

```
GET https://v3-api.proto.cx/api/platform/v1/conversations/{subcompany_id}/{conversation_id}/get-conversation-details
```

{% endcode %}

{% code title="Returns" overflow="wrap" %}

```
{
  "id": "string",
  "short_id": "string",
  "external_conversation_id": "string",
  "gateway": object,
  "gateway_profile": object,
  "creator": object,
  "assignments": [object],
  "team_assignments": [object],
  "active_assignee_id": "string",
  "active_assignee_name": "string",
  "active_assigned_team_ids": [string],
  "active_assigned_team_names": [string],
  "first_assigned_at": "string",
  "notes": [object],
  "tags": [object],
  "tag_groups": [object],
  "custom_fields": [object],
  "status": ""pending" | "open" | "sneakpeek" | "overdue" | "resolved" | "closed"",
  "type": ""livechat" | "ticket"",
  "subject": "string",
  "description": "string",
  "linked_conversation_id": "string",
  "last_msg_id": "string",
  "last_msg_sent_at": "string",
  "created_at": "string",
  "closed_by": "string",
  "closed_at": "string",
  "closed_by_type": ""user" | "chatbot" | "gateway_profile" | "external" | "transferred_bot""
}
```

{% endcode %}

***

### [**Get conversation messages**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/get_conversation_messages_v1_conversations__subcompany_id__conversation__conversation_id__messages_get)

Returns every message in a single conversation, in order.

{% code title="URL" overflow="wrap" %}

```
GET https://v3-api.proto.cx/api/platform/v1/conversations/{subcompany_id}/conversation/{conversation_id}/messages
```

{% endcode %}

***

### [**Send message**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/send_message_v1_conversations__subcompany_id___conversation_id__send_outbound_message_post)

Sends a message to the person in an existing conversation, attributed to the user in **user\_id**. Supports attachments, and an email template and subject for ticket conversations.

{% code title="URL" overflow="wrap" %}

```
POST https://v3-api.proto.cx/api/platform/v1/conversations/{subcompany_id}/{conversation_id}/send-outbound-message
```

{% endcode %}

{% code title="Body" overflow="wrap" %}

```
{
  "subject": "string",
  "content": "string" (required),
  "user_id": "string" (required),
  "attachment_ids": [string],
  "email_template_id": "string"
}
```

{% endcode %}

***

### [**Send internal note**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/send_internal_note_v1_conversations__subcompany_id___conversation_id__send_internal_note_post)

Adds an internal note to a conversation, attributed to the user in **user\_id**. Notes are visible only to live agents and are never sent to the person.

{% code title="URL" overflow="wrap" %}

```
POST https://v3-api.proto.cx/api/platform/v1/conversations/{subcompany_id}/{conversation_id}/send-internal-note
```

{% endcode %}

{% code title="Body" overflow="wrap" %}

```
{
  "content": "string" (required),
  "user_id": "string" (required)
}
```

{% endcode %}

{% hint style="warning" %}
Internal notes are never delivered to the person — see [Message editor](/docs/modules/inbox/message-editor.md).
{% endhint %}

***

### [**Update status**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/update_status_v1_conversations__subcompany_id___conversation_id__update_status_post)

Changes a conversation's status, for example to resolved or closed.

{% code title="URL" overflow="wrap" %}

```
POST https://v3-api.proto.cx/api/platform/v1/conversations/{subcompany_id}/{conversation_id}/update-status
```

{% endcode %}

{% code title="Body" overflow="wrap" %}

```
{
  "status": ""open" | "pending" | "resolved" | "closed" | "overdue"" (required)
}
```

{% endcode %}

***

### [**List tickets**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/list_tickets_v1_conversations__subcompany_id___start_date___end_date__tickets_get)

Lists ticket conversations created within the given date range.

{% code title="URL" overflow="wrap" %}

```
GET https://v3-api.proto.cx/api/platform/v1/conversations/{subcompany_id}/{start_date}/{end_date}/tickets
```

{% endcode %}

***

### [**List livechats**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/list_livechats_v1_conversations__subcompany_id___start_date___end_date__livechats_get)

Lists livechat conversations created within the given date range.

{% code title="URL" overflow="wrap" %}

```
GET https://v3-api.proto.cx/api/platform/v1/conversations/{subcompany_id}/{start_date}/{end_date}/livechats
```

{% endcode %}

***

### [**List messages**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/list_messages_v1_conversations__subcompany_id___start_date___end_date___ct__messages_get)

Lists messages across conversations of the given type within a date range.

{% code title="URL" overflow="wrap" %}

```
GET https://v3-api.proto.cx/api/platform/v1/conversations/{subcompany_id}/{start_date}/{end_date}/{ct}/messages
```

{% endcode %}

***

### [**List messages (v2 platform)**](https://v3-api.proto.cx/api/platform/v1/docs#/v1/list_messages_v2_v1_conversations__subcompany_id___start_date___end_date___ct__messages_v2_get)

Lists messages across conversations of the given type within a date range, for the earlier platform edition.

{% code title="URL" overflow="wrap" %}

```
GET https://v3-api.proto.cx/api/platform/v1/conversations/{subcompany_id}/{start_date}/{end_date}/{ct}/messages-v2
```

{% endcode %}