Conversations

Get started

Guides

REST reference

Conversations API

Conversations and their messages.

View as Markdown

List conversations

GET/v1/conversations

Cursor-paginated conversations, newest first.

Required scope: conversations:read.

Parameters

limitinteger

Page size (1–100).

starting_afterstring

Cursor: the `id` of the last item from the previous page.

statusstring

One of: open, closed.

channelstring

One of: api, widget, whatsapp, facebook, instagram, telegram.

channel_idstring

customer_idstring

prioritystring

One of: low, normal, high, urgent.

Request

cURL

curl "https://api.asks.app/v1/conversations" \
  -H "Authorization: Bearer $ASKS_API_KEY"

Response 200

JSON

{
  "object": "list",
  "data": [
    {
      "object": "conversation",
      "id": "string",
      "status": "open",
      "channel": "api",
      "channel_id": {},
      "customer_id": {},
      "customer_name": {},
      "customer_email": {},
      "assignee": {},
      "priority": "low",
      "tags": [
        "string"
      ],
      "external_id": {},
      "is_pinned": true,
      "resolution_type": "confirmed",
      "message_count": 1,
      "custom_action_memory": {},
      "resolved_at": {},
      "created_at": {},
      "updated_at": {}
    }
  ],
  "has_more": true,
  "next_cursor": {}
}

Create a conversation

POST/v1/conversations

Creates a conversation. If customer info is provided, the customer is created or matched (cross-channel dedup).

Required scope: conversations:write.

Request body

channelstring

One of: api, widget, whatsapp, facebook, instagram, telegram.

customerobject

Identifying info used to create or match a customer.

metadataobject

Request

cURL

curl -X POST "https://api.asks.app/v1/conversations" \
  -H "Authorization: Bearer $ASKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "api",
    "customer": {
      "email": "customer@example.com",
      "phone": "string",
      "name": "string",
      "external_id": "string"
    },
    "metadata": {}
  }'

Response 201

JSON

{
  "object": "conversation",
  "id": "string",
  "status": "open",
  "channel": "api",
  "channel_id": {},
  "customer_id": {},
  "customer_name": {},
  "customer_email": {},
  "assignee": {},
  "priority": "low",
  "tags": [
    "string"
  ],
  "external_id": {},
  "is_pinned": true,
  "resolution_type": "confirmed",
  "message_count": 1,
  "custom_action_memory": {},
  "resolved_at": {},
  "created_at": {},
  "updated_at": {}
}

Retrieve a conversation

GET/v1/conversations/{id}

Required scope: conversations:read.

Request

cURL

curl "https://api.asks.app/v1/conversations/<id>" \
  -H "Authorization: Bearer $ASKS_API_KEY"

Response 200

JSON

{
  "object": "conversation",
  "id": "string",
  "status": "open",
  "channel": "api",
  "channel_id": {},
  "customer_id": {},
  "customer_name": {},
  "customer_email": {},
  "assignee": {},
  "priority": "low",
  "tags": [
    "string"
  ],
  "external_id": {},
  "is_pinned": true,
  "resolution_type": "confirmed",
  "message_count": 1,
  "custom_action_memory": {},
  "resolved_at": {},
  "created_at": {},
  "updated_at": {}
}

Update a conversation

PATCH/v1/conversations/{id}

Update status, priority, tags, or assignment. assignee accepts "ai", a user id, or null.

Required scope: conversations:write.

Request body

statusstring

`resolved` is accepted as a legacy alias for `closed`. One of: open, closed.

prioritystring

One of: low, normal, high, urgent.

tagsarray of string

assigneestringnull

`"ai"`, a user id, or `null` to unassign.

Request

cURL

curl -X PATCH "https://api.asks.app/v1/conversations/<id>" \
  -H "Authorization: Bearer $ASKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "open",
    "priority": "low",
    "tags": [
      "string"
    ],
    "assignee": {}
  }'

Response 200

JSON

{
  "object": "conversation",
  "id": "string",
  "status": "open",
  "channel": "api",
  "channel_id": {},
  "customer_id": {},
  "customer_name": {},
  "customer_email": {},
  "assignee": {},
  "priority": "low",
  "tags": [
    "string"
  ],
  "external_id": {},
  "is_pinned": true,
  "resolution_type": "confirmed",
  "message_count": 1,
  "custom_action_memory": {},
  "resolved_at": {},
  "created_at": {},
  "updated_at": {}
}

List messages

GET/v1/conversations/{id}/messages

Cursor-paginated messages, newest first.

Required scope: conversations:read.

Parameters

limitinteger

Page size (1–100).

starting_afterstring

Cursor: the `id` of the last item from the previous page.

Request

cURL

curl "https://api.asks.app/v1/conversations/<id>/messages" \
  -H "Authorization: Bearer $ASKS_API_KEY"

Response 200

JSON

{
  "object": "list",
  "data": [
    {
      "object": "message",
      "id": "string",
      "conversation_id": "string",
      "ticket_id": {},
      "sender_type": "customer",
      "sender_id": {},
      "content": "string",
      "visibility": "public",
      "channel": "string",
      "external_id": {},
      "attachments": {},
      "is_read": true,
      "created_at": {}
    }
  ],
  "has_more": true,
  "next_cursor": {}
}

Send a message

POST/v1/conversations/{id}/messages

Posts an agent message into the conversation. Emits a message.created webhook.

Required scope: messages:write.

Request body

contentstringrequired

attachmentsarray of object

channel_metadataobject

client_message_idstring

Your own id for client-side dedup.

Request

cURL

curl -X POST "https://api.asks.app/v1/conversations/<id>/messages" \
  -H "Authorization: Bearer $ASKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "string",
    "attachments": [
      {}
    ],
    "channel_metadata": {},
    "client_message_id": "string"
  }'

Response 201

JSON

{
  "object": "message",
  "id": "string",
  "conversation_id": "string",
  "ticket_id": {},
  "sender_type": "customer",
  "sender_id": {},
  "content": "string",
  "visibility": "public",
  "channel": "string",
  "external_id": {},
  "attachments": {},
  "is_read": true,
  "created_at": {}
}

← Previous

Agent

Customers