Global Clinic ConnectGuides
Integration step 03

Synchronize conversations

Read conversation summaries and messages for a connected inbox or workflow system.

OutcomeA bounded, privacy-conscious conversation synchronization flow
Required scopesconversations:read
Step by step

Typical integration workflow

01

List recent conversations

Start with a modest limit and an optional channel filter.

02

Continue with the cursor

When next_cursor is present, send it unchanged to request the next page.

03

Read messages on demand

Use a conversation_id returned by the list endpoint and request only the message count your workflow needs.

04

Track delivery evidence

For WhatsApp messages, use the wa status fields when present. Absence of a delivery timestamp is not proof of delivery.

05

Protect synchronized content

Apply the same access, retention, encryption, and support controls to copied conversation data.

API reference

Endpoints for this capability

These are the supported public contracts for this integration step.

GET/api/public/v1/conversations?channel=whatsapp&limit=25
Scope · conversations:read

List conversations

Read a recent page of conversations, optionally limited to one channel.

Example request
GET /api/public/v1/conversations?channel=whatsapp&limit=25
Authorization: Bearer YOUR_API_KEY
Accept: application/json
Example response
{
  "conversations": [
    {
      "conversation_id": "conv_example",
      "channel": "whatsapp",
      "status": "open",
      "last_message_at": "2026-07-12T08:30:00.000Z",
      "last_message_preview": "Your appointment is confirmed"
    }
  ],
  "next_cursor": null
}

Error handling

400invalid channel filter

Use web_chat, sms, whatsapp, or email as the channel.

403INSUFFICIENT_SCOPE

Create a key with conversations:read.

429RATE_LIMITED

Pause until the current minute ends.

Best practices

  • Use next_cursor exactly as returned.
  • Keep page sizes modest for responsive synchronization.
  • Store only the conversation information your integration needs.
  • Protect message previews as sensitive data.
Try this endpoint in the console
GET/api/public/v1/conversations/{conversation_id}/messages?limit=50
Scope · conversations:read

List messages in a conversation

Read recent messages and delivery information for one conversation.

Example request
GET /api/public/v1/conversations/{conversation_id}/messages?limit=50
Authorization: Bearer YOUR_API_KEY
Accept: application/json
Example response
{
  "conversation_id": "conv_example",
  "messages": [
    {
      "message_id": "msg_example",
      "direction": "outbound",
      "created_at": "2026-07-12T08:31:00.000Z",
      "wa": { "provider_status": "delivered", "delivered_at": "2026-07-12T08:31:04.000Z" }
    }
  ]
}

Error handling

404CONVERSATION_NOT_FOUND

Confirm the ID came from the same workspace and key.

403INSUFFICIENT_SCOPE

Create a key with conversations:read.

429RATE_LIMITED

Back off and retry after the current minute.

Best practices

  • Read conversation IDs from the list endpoint.
  • Do not expose message content in logs.
  • Use provider status as delivery evidence only when it is present.
  • Avoid polling more often than your workflow needs.
Try this endpoint in the console
Production checklist

Best practices

  • ✓Prefer incremental pages over frequent full synchronization.
  • ✓Do not expose message previews in ordinary application logs.
  • ✓Keep the cursor opaque.
  • ✓Delete copied content when your approved retention period ends.
Interactive console

Try a supported API

Requests go directly from this browser tab to the API environment you choose. Keys and responses are held in memory only and are cleared when the page closes.

Do not use real patient data in tests
GET/api/public/v1/conversations?channel=whatsapp&limit=25
Response
Ready when you are

Enter a test key, review the sample request, and send it. The response will appear here.

Equivalent cURL example
curl -X GET 'https://api.connect.globalclinic.app/api/public/v1/conversations?channel=whatsapp&limit=25' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json'
Required scopeconversations:read

Read a recent page of conversations, optionally limited to one channel.

Next steps