Get a conversation

GET/api/v1/conversations/{id}

Since: 1.14.0
Auth: Bearer key
SDK: client.getConversation()
operationId: getConversation

One conversation with its patient, the channels a message can go out on now (and why not, for the others), and the clinic's reply templates filled in for this patient (empty when the clinic does not use templates). Use it before POST /conversations/{id}/messages to pick a channel that will be accepted. Needs the scope conversations:read; the read is written to the clinic's audit log. The response holds patient data and is never cached (Cache-Control: no-store); call it from your server only.

Request

Send the clinic's key in Authorization: Bearer (see API keys).

Path parameters

idstringrequired
The conversation id (conversationId of webhook events).

cURLTypeScriptPHP

curl "https://app.pozyskajpacjenta.pl/api/v1/conversations/Vb3nQ8sLk2PzX5wRt9YcE" \
  -H "Authorization: Bearer $PP_API_KEY"

import { PozyskajPacjentaClient } from "@pozyskajpacjenta/sdk";

const client = new PozyskajPacjentaClient({
  apiKey: process.env.PP_API_KEY ?? "",
  baseUrl: "https://app.pozyskajpacjenta.pl",
});

const { conversation, channels, templates } = await client.getConversation(
  "Vb3nQ8sLk2PzX5wRt9YcE",
);

<?php
$response = wp_remote_get(
    'https://app.pozyskajpacjenta.pl/api/v1/conversations/Vb3nQ8sLk2PzX5wRt9YcE',
    array(
        'headers' => array( 'Authorization' => 'Bearer ' . getenv( 'PP_API_KEY' ) ),
        'timeout' => 10,
    )
);
if ( is_wp_error( $response ) ) {
    error_log( $response->get_error_message() );
    return;
}
$status = wp_remote_retrieve_response_code( $response );
$data   = json_decode( wp_remote_retrieve_body( $response ), true );

Response

200The conversation.

conversationConversationrequired
The conversation.
Fields (9)
- idstringrequired
  Conversation id.
- statusstringrequired
  open or closed. The clinic closes a conversation in its inbox; a new message from the patient opens it again.
  One of openclosed
- leadConversationLeadrequired
  The patient.
  Fields (9)
  - idstringrequired
    The lead id: the leadId POST /leads returns and webhook events carry.
  - namestring | nullrequired
    The patient's name; null when unknown.
  - phonestring | nullrequired
    The patient's phone; null when unknown.
  - emailstring | nullrequired
    The patient's e-mail; null when unknown.
  - messagestring | nullrequired
    The enquiry the patient sent: a form's message or the first chat message. null when there was none.
  - sourcestringrequired
    Where the lead came from: form, embed, api, manual, inbound or chat.
  - stagestringrequired
    The lead's stage in the clinic's CRM, e.g. new, scheduled, visited, not_interested.
  - locationIdstring | nullrequired
    The clinic location the enquiry is for (GET /locations); null when not known.
  - createdAtstring (date-time)required
    When the lead was created.
- lastChannelstring | nullrequired
  Channel of the newest message: email, sms, whatsapp, instagram or chat (the chat on the clinic's site). null before the first message.
  One of emailsmswhatsappinstagramchat
- lastMessageAtstring (date-time) | nullrequired
  Time of the newest message; null before the first one.
- lastInboundAtstring (date-time) | nullrequired
  Time of the patient's newest message; null when the patient has not written.
- unreadCountintegerrequired
  The patient's messages nobody at the clinic has opened yet.
- createdAtstring (date-time)required
  When the conversation began.
- updatedAtstring (date-time)required
  The later of the conversation's last change (a message, a read, open or closed) and the lead's (stage, contact data). The updated_since filter compares with it; delivery receipts do not change it.
channelsConversationChannelState[]required
Every channel, in a fixed order, with whether a message can go out on it now.
Fields of each item (3)
- channelstringrequired
  The channel: email, sms, whatsapp, instagram or chat (the chat on the clinic's site).
  One of emailsmswhatsappinstagramchat
- availablebooleanrequired
  true when a message sent now would be accepted.
- reasonstring | nullrequired
  Why not, when available is false: the code a send would get in its 409 (see SendRefused). null when available.
  One of lead_archivedopted_outno_emailemail_domain_not_configuredno_phoneno_smsapi_tokenchat_not_startedmeta_platform_disabledwa_not_configuredwa_window_closedig_not_configuredig_no_user_idig_no_user_threadig_window_closedtemplate_not_foundtemplate_channel
templatesConversationTemplate[]required
The clinic's reply templates, filled in for this patient.
Fields of each item (4)
- idstringrequired
  Template id: the templateId of POST /conversations/{id}/messages.
- namestringrequired
  The template's name in the clinic's inbox.
- textstringrequired
  The text the patient would get.
- channelsstring[] | nullrequired
  The channels the template suits; null means every channel.
  One of emailsmswhatsappinstagramchat

200

A conversation: SMS available, e-mail opted out (templates trimmed to two)

{
  "conversation": {
    "id": "Vb3nQ8sLk2PzX5wRt9YcE",
    "status": "open",
    "lead": {
      "id": "rS2bIhedVSStSQLc7DL_T",
      "name": "Anna Kowalska",
      "phone": "+48 600 100 200",
      "email": "anna.kowalska@example.com",
      "message": "Proszę o kontakt w sprawie higienizacji.",
      "source": "form",
      "stage": "scheduled",
      "locationId": "loc_wieliczka",
      "createdAt": "2026-10-12T07:41:09.000Z"
    },
    "lastChannel": "sms",
    "lastMessageAt": "2026-10-12T08:02:44.000Z",
    "lastInboundAt": "2026-10-12T08:02:44.000Z",
    "unreadCount": 1,
    "createdAt": "2026-10-12T07:52:10.000Z",
    "updatedAt": "2026-10-12T08:02:44.000Z"
  },
  "channels": [
    {
      "channel": "email",
      "available": false,
      "reason": "opted_out"
    },
    {
      "channel": "sms",
      "available": true,
      "reason": null
    },
    {
      "channel": "whatsapp",
      "available": false,
      "reason": "wa_window_closed"
    },
    {
      "channel": "instagram",
      "available": false,
      "reason": "ig_not_configured"
    },
    {
      "channel": "chat",
      "available": false,
      "reason": "chat_not_started"
    }
  ],
  "templates": [
    {
      "id": "nHv4l_ALArlouEEfxHLOO",
      "name": "Rezerwacja online",
      "text": "Dzień dobry Anna, wolne terminy i rezerwacja online: https://wzorcowa.pozyskajpacjenta.pl Klinika Wzorcowa",
      "channels": null
    },
    {
      "id": "Olz1kaJ9PjjlsZXlBtly3",
      "name": "Jak do nas trafić",
      "text": "Zapraszamy: ul. Przykładowa 12, 00-950 Warszawa. W razie pytań prosimy dzwonić: +48 22 100 20 30. Klinika Wzorcowa",
      "channels": null
    }
  ]
}

Errors

Status	code	When
401		No Authorization header
401		Unknown or rotated key
403	`missing_scope`	The key lacks conversations:read
404	`not_found`	Unknown id, another clinic's conversation or an archived lead's
429		Over 120 requests in this minute

Branch on the status and code, never on the Polish error text. All statuses in Errors.

401 · No Authorization header

{
  "error": "missing Authorization: Bearer <klucz z panelu Ustawienia>"
}

401 · Unknown or rotated key

{
  "error": "invalid key"
}

403 · The key lacks conversations:read

{
  "error": "Klucz nie ma uprawnienia conversations:read. Placówka nadaje je w panelu: Ustawienia › Integracje › Klucz API.",
  "code": "missing_scope",
  "scope": "conversations:read"
}

404 · Unknown id, another clinic's conversation or an archived lead's

{
  "error": "Nie ma takiej rozmowy.",
  "code": "not_found"
}

429 · Over 120 requests in this minute

{
  "error": "przekroczono limit 120 zapytań/min"
}

Rate limit

120 requests per minute per key, shared by every endpoint.
Every response to a valid key carries RateLimit-Remaining and RateLimit-Reset; see Rate limits.

SDK method

client.getConversation(id: string): Promise<ConversationDetail>

Throws ApiError 404 for an unknown conversation; 403 without the scope.

The TypeScript tab above uses it. Install and errors: TypeScript SDK.