Conversations

#List conversations

Tenant conversations in ascending updated_at order, paged by cursor: to pick up changes, keep the updated_at of the last one you saw and pass it as updated_after. Conversations have no soft deletion, so include_deleted adds nothing for now. The response contains customer personal data: every disclosure is recorded in the disclosure log; on RU an IP allowlist and recipient country RU are required (otherwise 403 pii_transfer_not_allowed). Personal-mailbox conversations and student-portal chats are not returned. Personal-data fields (external_customer_id of a conversation; content and attachments of a message) are returned only when named in fields=. On the EN and ID cells their values may come in JWE format (the integration mode and the Encryption-Key-Id header); in mode required without a key — 409 encryption_key_required.

Scopes

conversations:read

Rate limit

read

Idempotency

not required

Successful response

200 A page of conversations.

Parameters

Response body

Examples

curl -X GET 'https://wfacademy.id/api/public/v1/conversations' \
  -H 'Authorization: Bearer '"$API_KEY"

{
  "data": [
    {
      "id": "EXAMPLE_ID",
      "channel": null,
      "contact_id": null,
      "external_customer_id": null,
      "status": "string",
      "mode": "ai",
      "language": null,
      "created_at": null,
      "updated_at": "2026-10-11T09:00:00Z",
      "_enc": [
        null
      ]
    }
  ],
  "next_cursor": "EXAMPLE_CURSOR"
}

{
  "type": "https://wfacademy.id/developers/errors#scope_missing",
  "title": "Scope is missing",
  "status": 403,
  "code": "scope_missing",
  "detail": "EXAMPLE",
  "request_id": "req_EXAMPLE"
}

Examples are illustrative: the key in them is a placeholder (EXAMPLE), field values are made up.

Possible errors

invalid_api_key wrong_cell integration_inactive tenant_inactive ip_not_allowed feature_not_in_plan rate_limited wallet_suspended service_unavailable internal_error scope_missing pii_transfer_not_allowed validation_failed encryption_key_required

#Find or create a conversation

A conversation of your channel customer (the integration api channel) by the external id: an active one is returned (200), otherwise a new one is created (201) with a conversation.created event. The same external_customer_id of two integrations means two different customers. Name, email and phone are written into empty contact fields only. Connect the channel in the dashboard (Settings → API); without it — 409 channel_not_configured. A retry with the same Idempotency-Key returns the same conversation. The response contains customer personal data: every disclosure is recorded in the disclosure log; on RU an IP allowlist and recipient country RU are required (otherwise 403 pii_transfer_not_allowed). Personal-mailbox conversations and student-portal chats are not returned.

Scopes

conversations:write

Rate limit

write

Idempotency

Idempotency-Key is required

Successful response

201 The conversation (new — 201, existing — 200).

Parameters

Request body Your channel customer.

Response body

Examples

curl -X POST 'https://wfacademy.id/api/public/v1/conversations' \
  -H 'Authorization: Bearer '"$API_KEY" \
  -H 'Idempotency-Key: '"$(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "external_customer_id": "EXAMPLE_ID",
  "name": "string",
  "email": "[email protected]",
  "phone": "string",
  "language": "string"
}'

{
  "id": "EXAMPLE_ID",
  "channel": "string",
  "contact_id": "EXAMPLE_ID",
  "external_customer_id": "EXAMPLE_ID",
  "status": "string",
  "mode": "ai",
  "language": "string",
  "created_at": "2026-10-11T09:00:00Z",
  "updated_at": "2026-10-11T09:00:00Z",
  "_enc": [
    "string"
  ]
}

{
  "type": "https://wfacademy.id/developers/errors#scope_missing",
  "title": "Scope is missing",
  "status": 403,
  "code": "scope_missing",
  "detail": "EXAMPLE",
  "request_id": "req_EXAMPLE"
}

Examples are illustrative: the key in them is a placeholder (EXAMPLE), field values are made up.

Possible errors

invalid_api_key wrong_cell integration_inactive tenant_inactive ip_not_allowed feature_not_in_plan rate_limited wallet_suspended service_unavailable internal_error scope_missing pii_transfer_not_allowed validation_failed bad_request payload_too_large channel_not_configured idempotency_key_required idempotency_conflict operation_in_progress invalid_state

#Get a conversation

One conversation. A foreign, missing or non-public conversation all answer not_found alike. The response contains customer personal data: every disclosure is recorded in the disclosure log; on RU an IP allowlist and recipient country RU are required (otherwise 403 pii_transfer_not_allowed). Personal-mailbox conversations and student-portal chats are not returned. Personal-data fields (external_customer_id of a conversation; content and attachments of a message) are returned only when named in fields=. On the EN and ID cells their values may come in JWE format (the integration mode and the Encryption-Key-Id header); in mode required without a key — 409 encryption_key_required.

Scopes

conversations:read

Rate limit

read

Idempotency

not required

Successful response

200 The conversation.

Parameters

Response body

Examples

curl -X GET 'https://wfacademy.id/api/public/v1/conversations/EXAMPLE_ID' \
  -H 'Authorization: Bearer '"$API_KEY"

{
  "id": "EXAMPLE_ID",
  "channel": "string",
  "contact_id": "EXAMPLE_ID",
  "external_customer_id": "EXAMPLE_ID",
  "status": "string",
  "mode": "ai",
  "language": "string",
  "created_at": "2026-10-11T09:00:00Z",
  "updated_at": "2026-10-11T09:00:00Z",
  "_enc": [
    "string"
  ]
}

{
  "type": "https://wfacademy.id/developers/errors#scope_missing",
  "title": "Scope is missing",
  "status": 403,
  "code": "scope_missing",
  "detail": "EXAMPLE",
  "request_id": "req_EXAMPLE"
}

Examples are illustrative: the key in them is a placeholder (EXAMPLE), field values are made up.

Possible errors

invalid_api_key wrong_cell integration_inactive tenant_inactive ip_not_allowed feature_not_in_plan rate_limited wallet_suspended service_unavailable internal_error scope_missing pii_transfer_not_allowed not_found validation_failed encryption_key_required

#Conversation messages

Conversation messages from oldest to newest, paged by cursor (created_at, id). Operator internal notes are not returned. Attachments are temporary signed links; external messenger file addresses are not disclosed. The response contains customer personal data: every disclosure is recorded in the disclosure log; on RU an IP allowlist and recipient country RU are required (otherwise 403 pii_transfer_not_allowed). Personal-mailbox conversations and student-portal chats are not returned. Personal-data fields (external_customer_id of a conversation; content and attachments of a message) are returned only when named in fields=. On the EN and ID cells their values may come in JWE format (the integration mode and the Encryption-Key-Id header); in mode required without a key — 409 encryption_key_required.

Scopes

conversations:read

Rate limit

read

Idempotency

not required

Successful response

200 A page of messages.

Parameters

Response body

Examples

curl -X GET 'https://wfacademy.id/api/public/v1/conversations/EXAMPLE_ID/messages' \
  -H 'Authorization: Bearer '"$API_KEY"

{
  "data": [
    {
      "id": "EXAMPLE_ID",
      "conversation_id": "EXAMPLE_ID",
      "sender": "customer",
      "content_type": "string",
      "content": null,
      "attachments": null,
      "cards": [
        null
      ],
      "deleted": false,
      "created_at": "2026-10-11T09:00:00Z",
      "_enc": [
        null
      ]
    }
  ],
  "next_cursor": "EXAMPLE_CURSOR"
}

{
  "type": "https://wfacademy.id/developers/errors#scope_missing",
  "title": "Scope is missing",
  "status": 403,
  "code": "scope_missing",
  "detail": "EXAMPLE",
  "request_id": "req_EXAMPLE"
}

Examples are illustrative: the key in them is a placeholder (EXAMPLE), field values are made up.

Possible errors

invalid_api_key wrong_cell integration_inactive tenant_inactive ip_not_allowed feature_not_in_plan rate_limited wallet_suspended service_unavailable internal_error scope_missing pii_transfer_not_allowed not_found validation_failed encryption_key_required

#Customer message and AI reply

Saves a customer message into a conversation of the integration channel (conversations:write) and, with ai_reply=auto and the ai_seller:invoke scope, starts the AI seller reply asynchronously: 202 with message_id, ai_reply.status=queued and a conversation.ai_reply operation. ?wait=N (0–20 s) waits for the SAME job: in time — 200 with the result (ai_reply, reply.id, operation.usage.cost in the wallet currency), otherwise — 202. Without ai_seller:invoke or with ai_reply=none — 201, ai_reply.status=skipped, reason=not_requested; the AI is not called and nothing is charged. The AI reply text is not here — read GET /conversations/{id}/messages or wait for message.created. A retry with the same Idempotency-Key while running returns the same 202, afterwards the result; the message is never written or charged twice. Paid part: at most 5 concurrent operations per integration (429 concurrency_limit), the per-operation cost cap and the integration daily limit (402 spend_limit_reached) are checked before writing; a refusal writes nothing and frees the Idempotency-Key. A conversation of another channel or tenant — 404, a closed one — 409 invalid_state.

Scopes

conversations:write

Rate limit

write

Idempotency

Idempotency-Key is required

Successful response

202 Accepted; the AI reply is being prepared (202), ready within wait (200) or not requested (201).

Parameters

Request body The customer message.

Response body

Examples

curl -X POST 'https://wfacademy.id/api/public/v1/conversations/EXAMPLE_ID/messages' \
  -H 'Authorization: Bearer '"$API_KEY" \
  -H 'Idempotency-Key: '"$(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "content": "string",
  "ai_reply": "auto"
}'

{
  "message_id": "EXAMPLE_ID",
  "conversation_id": "EXAMPLE_ID",
  "ai_reply": {
    "status": "replied",
    "reason": "operator_active"
  },
  "reply": {
    "id": "EXAMPLE_ID"
  },
  "operation": {
    "id": "EXAMPLE_ID",
    "type": "string",
    "status": "queued",
    "created_at": "2026-10-11T09:00:00Z",
    "completed_at": "2026-10-11T09:00:00Z",
    "resource": {
      "type": "string",
      "id": "EXAMPLE_ID"
    },
    "error": {
      "code": "string",
      "message": "string"
    },
    "usage": {
      "cost": null,
      "model": null
    }
  }
}

{
  "type": "https://wfacademy.id/developers/errors#scope_missing",
  "title": "Scope is missing",
  "status": 403,
  "code": "scope_missing",
  "detail": "EXAMPLE",
  "request_id": "req_EXAMPLE"
}

Examples are illustrative: the key in them is a placeholder (EXAMPLE), field values are made up.

Possible errors

invalid_api_key wrong_cell integration_inactive tenant_inactive ip_not_allowed feature_not_in_plan rate_limited wallet_suspended service_unavailable internal_error scope_missing pii_transfer_not_allowed validation_failed bad_request payload_too_large not_found channel_not_configured invalid_state idempotency_key_required idempotency_conflict operation_in_progress concurrency_limit spend_limit_reached upstream_unavailable