Conversations
REST reference

Conversations API

Conversations and their messages.

View as Markdown

List conversations

GET/v1/conversations

Cursor-paginated conversations, newest first (order=last_message: most recently active first, on last_message_at).

With q, results are a single relevance-ranked page of at most limit (no cursor); each item carries match — a highlighted snippet (<mark> tags) of the best-matching message, its message_id, and in_internal_note when the hit is an agent note. q also matches the customer's name and email.

Required scope: conversations:read.

Parameters
limitinteger

Page size (1–100).

starting_afterstring

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

qstring

Full-text search over messages, internal notes and the customer's name/email.

assigneestring

`ai`, `escalated` (waiting for a human), `unassigned`, `me` (tokens that act for a member) or a user id.

last_message_afterstring
last_message_beforestring
orderstring

One of: created, last_message.

statusstring

One of: open, closed.

channelstring

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

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": {},
      "last_message_at": {},
      "match": {
        "snippet": {},
        "message_id": {},
        "in_internal_note": true
      },
      "messages": [
        {
          "object": null,
          "id": null,
          "conversation_id": null,
          "ticket_id": null,
          "sender_type": null,
          "sender_id": null,
          "content": null,
          "visibility": null,
          "channel": null,
          "external_id": null,
          "attachments": null,
          "is_read": null,
          "created_at": null,
          "kind": null,
          "delivery": null,
          "campaign": null,
          "preview_text": null,
          "context": null
        }
      ],
      "messages_has_more": true,
      "notes": [
        {
          "object": null,
          "id": null,
          "conversation_id": null,
          "ticket_id": null,
          "sender_type": null,
          "sender_id": null,
          "content": null,
          "visibility": null,
          "channel": null,
          "external_id": null,
          "attachments": null,
          "is_read": null,
          "created_at": null,
          "kind": null,
          "delivery": null,
          "campaign": null,
          "preview_text": null,
          "context": null
        }
      ],
      "notes_has_more": true
    }
  ],
  "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": {},
  "last_message_at": {},
  "match": {
    "snippet": {},
    "message_id": {},
    "in_internal_note": true
  },
  "messages": [
    {
      "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": {},
      "kind": "text",
      "delivery": {
        "status": "sent",
        "reason": "string"
      },
      "campaign": {
        "id": "string",
        "name": "string"
      },
      "preview_text": {},
      "context": {
        "caption": "string",
        "permalink": "string",
        "link": {
          "title": null,
          "url": null
        },
        "referral": {
          "source": null,
          "headline": null,
          "body": null,
          "ad_id": null,
          "ref": null,
          "product_id": null
        },
        "location": {
          "name": null,
          "address": null,
          "latitude": null,
          "longitude": null
        },
        "contact_names": [],
        "order_items": [],
        "product_items": []
      }
    }
  ],
  "messages_has_more": true,
  "notes": [
    {
      "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": {},
      "kind": "text",
      "delivery": {
        "status": "sent",
        "reason": "string"
      },
      "campaign": {
        "id": "string",
        "name": "string"
      },
      "preview_text": {},
      "context": {
        "caption": "string",
        "permalink": "string",
        "link": {
          "title": null,
          "url": null
        },
        "referral": {
          "source": null,
          "headline": null,
          "body": null,
          "ad_id": null,
          "ref": null,
          "product_id": null
        },
        "location": {
          "name": null,
          "address": null,
          "latitude": null,
          "longitude": null
        },
        "contact_names": [],
        "order_items": [],
        "product_items": []
      }
    }
  ],
  "notes_has_more": true
}

Retrieve a conversation

GET/v1/conversations/{id}

include=messages embeds the newest 50 customer-facing messages (messages, newest first, + messages_has_more); include=notes embeds the newest 50 internal agent notes (notes, + notes_has_more). Combine with a comma.

Required scope: conversations:read.

Parameters
includestring

Comma-separated: `messages`, `notes`.

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": {},
  "last_message_at": {},
  "match": {
    "snippet": {},
    "message_id": {},
    "in_internal_note": true
  },
  "messages": [
    {
      "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": {},
      "kind": "text",
      "delivery": {
        "status": "sent",
        "reason": "string"
      },
      "campaign": {
        "id": "string",
        "name": "string"
      },
      "preview_text": {},
      "context": {
        "caption": "string",
        "permalink": "string",
        "link": {
          "title": null,
          "url": null
        },
        "referral": {
          "source": null,
          "headline": null,
          "body": null,
          "ad_id": null,
          "ref": null,
          "product_id": null
        },
        "location": {
          "name": null,
          "address": null,
          "latitude": null,
          "longitude": null
        },
        "contact_names": [],
        "order_items": [],
        "product_items": []
      }
    }
  ],
  "messages_has_more": true,
  "notes": [
    {
      "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": {},
      "kind": "text",
      "delivery": {
        "status": "sent",
        "reason": "string"
      },
      "campaign": {
        "id": "string",
        "name": "string"
      },
      "preview_text": {},
      "context": {
        "caption": "string",
        "permalink": "string",
        "link": {
          "title": null,
          "url": null
        },
        "referral": {
          "source": null,
          "headline": null,
          "body": null,
          "ad_id": null,
          "ref": null,
          "product_id": null
        },
        "location": {
          "name": null,
          "address": null,
          "latitude": null,
          "longitude": null
        },
        "contact_names": [],
        "order_items": [],
        "product_items": []
      }
    }
  ],
  "notes_has_more": true
}

Update a conversation

PATCH/v1/conversations/{id}

Update status, priority, tags, or assignment — the same path as the dashboard: closing records the resolution, closes the linked ticket with one lifecycle note, emails the customer the resolved/rate-us message and emits conversation.updated + conversation.closed; assigning a member takes over from the AI; assignee: "ai" hands back to the AI and answers 409 conflict when the AI can't serve the conversation (agent off, not deployed on the channel, AI off for the channel). tags replaces the list.

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": {},
  "last_message_at": {},
  "match": {
    "snippet": {},
    "message_id": {},
    "in_internal_note": true
  },
  "messages": [
    {
      "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": {},
      "kind": "text",
      "delivery": {
        "status": "sent",
        "reason": "string"
      },
      "campaign": {
        "id": "string",
        "name": "string"
      },
      "preview_text": {},
      "context": {
        "caption": "string",
        "permalink": "string",
        "link": {
          "title": null,
          "url": null
        },
        "referral": {
          "source": null,
          "headline": null,
          "body": null,
          "ad_id": null,
          "ref": null,
          "product_id": null
        },
        "location": {
          "name": null,
          "address": null,
          "latitude": null,
          "longitude": null
        },
        "contact_names": [],
        "order_items": [],
        "product_items": []
      }
    }
  ],
  "messages_has_more": true,
  "notes": [
    {
      "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": {},
      "kind": "text",
      "delivery": {
        "status": "sent",
        "reason": "string"
      },
      "campaign": {
        "id": "string",
        "name": "string"
      },
      "preview_text": {},
      "context": {
        "caption": "string",
        "permalink": "string",
        "link": {
          "title": null,
          "url": null
        },
        "referral": {
          "source": null,
          "headline": null,
          "body": null,
          "ad_id": null,
          "ref": null,
          "product_id": null
        },
        "location": {
          "name": null,
          "address": null,
          "latitude": null,
          "longitude": null
        },
        "contact_names": [],
        "order_items": [],
        "product_items": []
      }
    }
  ],
  "notes_has_more": true
}

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": {},
      "kind": "text",
      "delivery": {
        "status": "sent",
        "reason": "string"
      },
      "campaign": {
        "id": "string",
        "name": "string"
      },
      "preview_text": {},
      "context": {
        "caption": "string",
        "permalink": "string",
        "link": {
          "title": null,
          "url": null
        },
        "referral": {
          "source": null,
          "headline": null,
          "body": null,
          "ad_id": null,
          "ref": null,
          "product_id": null
        },
        "location": {
          "name": null,
          "address": null,
          "latitude": null,
          "longitude": null
        },
        "contact_names": [],
        "order_items": [],
        "product_items": []
      }
    }
  ],
  "has_more": true,
  "next_cursor": {}
}

Send a message

POST/v1/conversations/{id}/messages

Posts an agent message into the conversation and sends it to the customer on the conversation's channel. Emits a message.created webhook. The response adds delivery: sent (forwarded to the channel or pushed to the live widget), stored (nothing to deliver to — api-channel conversations), or failed with a reason (e.g. the WhatsApp/Instagram messaging window is closed). A token that acts for a member (an MCP connection) sends as that member.

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": {},
  "kind": "text",
  "delivery": {
    "status": "sent",
    "reason": "string"
  },
  "campaign": {
    "id": "string",
    "name": "string"
  },
  "preview_text": {},
  "context": {
    "caption": "string",
    "permalink": "string",
    "link": {
      "title": "string",
      "url": "string"
    },
    "referral": {
      "source": "ad",
      "headline": "string",
      "body": "string",
      "ad_id": "string",
      "ref": "string",
      "product_id": "string"
    },
    "location": {
      "name": "string",
      "address": "string",
      "latitude": 1,
      "longitude": 1
    },
    "contact_names": [
      "string"
    ],
    "order_items": [
      {
        "retailer_id": "string",
        "quantity": 1,
        "price": 1,
        "currency": "string",
        "title": "string",
        "variant_title": "string",
        "sku": "string",
        "product_url": "string"
      }
    ],
    "product_items": [
      {
        "id": "string",
        "retailer_id": "string",
        "title": "string",
        "product_url": "string"
      }
    ]
  }
}

Add an internal note

POST/v1/conversations/{id}/notes

Adds an internal note for your team (visibility internal). It is never sent to the customer. A token that acts for a member writes the note as that member; an API key writes it as the key's creator (or the workspace owner).

Required scope: conversations:write.

Request body
contentstringrequired
Request
cURL
curl -X POST "https://api.asks.app/v1/conversations/<id>/notes" \
  -H "Authorization: Bearer $ASKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "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": {},
  "kind": "text",
  "delivery": {
    "status": "sent",
    "reason": "string"
  },
  "campaign": {
    "id": "string",
    "name": "string"
  },
  "preview_text": {},
  "context": {
    "caption": "string",
    "permalink": "string",
    "link": {
      "title": "string",
      "url": "string"
    },
    "referral": {
      "source": "ad",
      "headline": "string",
      "body": "string",
      "ad_id": "string",
      "ref": "string",
      "product_id": "string"
    },
    "location": {
      "name": "string",
      "address": "string",
      "latitude": 1,
      "longitude": 1
    },
    "contact_names": [
      "string"
    ],
    "order_items": [
      {
        "retailer_id": "string",
        "quantity": 1,
        "price": 1,
        "currency": "string",
        "title": "string",
        "variant_title": "string",
        "sku": "string",
        "product_url": "string"
      }
    ],
    "product_items": [
      {
        "id": "string",
        "retailer_id": "string",
        "title": "string",
        "product_url": "string"
      }
    ]
  }
}
← Previous
Agent
Next →
Customers
Chat on WhatsApp