Sync WhatsApp conversations

The two WhatsApp endpoints are read-only: they let you list conversations with their transcripts and drill into a single conversation’s full message history — for reporting, quality review, or keeping a copy in your own CRM.

List WhatsApp conversations — GET /api/v2/public/whatsapp/conversations
List messages in a WhatsApp conversation — GET /api/v2/public/whatsapp/conversations/{session_id}/messages

The endpoint pages document every parameter and field; this guide is about using them well.

Concepts

A conversation (a session) is one bounded WhatsApp conversation window with a single customer phone number. A customer accumulates several conversations over time as windows open and close.
Each conversation belongs to a client (when the number is matched to a contact) and contains an ordered list of messages.
Conversations carry a status (new, ai_handling, human_handling, resolved, expired), a direction (inbound / outbound), an optional disposition tag and an optional sentiment.

Who sent what

Three fields answer three different questions — do not confuse them:

Field	Level	Answers
`messages[].sender`	message	Who sent this message — the specific AI agent, team member, or the client.
`participants`	conversation	Who replied in this conversation — every AI agent and team member that sent at least one message, with counts.
`assigned_users`	customer	Who owns this customer — their Salesflow pipeline assignee(s). Says nothing about who replied.

A single conversation routinely mixes several people and one or more AI agents (a bot handles the opening, a person takes over, another person closes it), which is why participants exists separately from assigned_users. participants is always complete — it covers the whole conversation even when you request include_messages=false or the transcript is truncated. Only identified senders appear; messages synced from the WhatsApp Business app carry no attributable sender and contribute to no entry.

Common requests

Metadata-only browse
Full transcripts, newest first
Filter by client and disposition
Messages per team member

The fastest way to see what exists. participants is still fully populated.

curl -H "Authorization: Bearer pk_xxx" \
  "https://api.dialtu.com/api/v2/public/whatsapp/conversations?limit=20&include_messages=false"

curl -H "Authorization: Bearer pk_xxx" \
  "https://api.dialtu.com/api/v2/public/whatsapp/conversations?limit=10&sort_by=-created_at"

Repeat disposition_tag_ids for an OR filter; add include_uncategorized=true to also get conversations with no disposition.

curl -H "Authorization: Bearer pk_xxx" \
  "https://api.dialtu.com/api/v2/public/whatsapp/conversations?client_id=2&disposition_tag_ids=1&disposition_tag_ids=2&include_uncategorized=true"

Because participants is populated without transcripts, per-agent and per-person reporting is cheap:

curl -H "Authorization: Bearer pk_xxx" \
  "https://api.dialtu.com/api/v2/public/whatsapp/conversations?limit=50&include_messages=false&created_after=2026-06-01T00:00:00Z" \
| jq '[.data[].participants.users[]]
      | group_by(.id)
      | map({ id: .[0].id, name: .[0].name, messages: (map(.message_count) | add) })
      | sort_by(-.messages)'

Incremental sync

Do not re-download everything on each run:

Store the newest updated_at you have seen

Every conversation carries updated_at, which moves whenever a message arrives or the status, disposition or summary changes.

Ask only for what changed

On the next run pass that timestamp as updated_after and sort with sort_by=updated_at for predictable ordering:

curl -H "Authorization: Bearer pk_xxx" \
  "https://api.dialtu.com/api/v2/public/whatsapp/conversations?updated_after=2026-06-30T00:00:00Z&sort_by=updated_at"

Page through the result

Keep the same filters and increase offset by limit until you have read count items.

Long conversations

Each conversation embeds at most max_messages_per_session messages (default 500, oldest first). A longer transcript is truncated and flagged with has_more_messages: true — fetch the rest with the messages endpoint, paging with limit / offset:

curl -H "Authorization: Bearer pk_xxx" \
  "https://api.dialtu.com/api/v2/public/whatsapp/conversations/60/messages?limit=100&offset=0"

The messages endpoint also returns the conversation’s full participants roster, so you never need a second call to the list endpoint just for that.

Sample conversation

{
  "session_id": 61,
  "status": "ai_handling",
  "direction": "inbound",
  "customer_phone_number": "+573013449768",
  "client": { "id": 2, "name": "Christian Gallo", "first_name": "Christian", "last_name": "Gallo", "phone": "3013449768", "email": null, "company": null },
  "disposition": null,
  "sentiment": null,
  "summary": "",
  "message_count": 2,
  "has_more_messages": false,
  "created_at": "2026-06-30T15:39:33.437Z",
  "updated_at": "2026-06-30T15:39:39.080Z",
  "last_message_at": "2026-06-30T15:39:51.309Z",
  "messages": [
    {
      "id": 561, "sender_type": "customer",
      "sender": { "type": "client", "id": 2, "name": "Christian Gallo", "email": null },
      "message_type": "text",
      "content": "Hola, ¿qué horarios hay disponibles?",
      "timestamp": "2026-06-30T15:39:33.482Z",
      "media": null, "reply_to_id": null
    },
    {
      "id": 562, "sender_type": "ai",
      "sender": { "type": "ai_agent", "id": 7, "name": "Sofia", "email": null },
      "message_type": "text",
      "content": "¡Hola! Tenemos disponibilidad mañana a las 10:00.",
      "timestamp": "2026-06-30T15:39:39.080Z",
      "media": null, "reply_to_id": 561
    }
  ],
  "assigned_users": [ { "id": 42, "name": "Ana Perez", "email": "ana@acme.com" } ],
  "participants": {
    "ai_agents": [ { "id": 7, "name": "Sofia", "message_count": 1, "first_message_at": "2026-06-30T15:39:39.080Z", "last_message_at": "2026-06-30T15:39:39.080Z" } ],
    "users": []
  }
}

Notes and limits

Read-only. These endpoints never modify conversations.
Media files are not downloadable — only kind, mime, filename and caption are returned.
Internal fields (model, tokens, cost, storage keys) are never exposed.
Additive changes. New fields may be added (sender and participants arrived this way, next to an unchanged sender_type). Ignore fields you do not recognise.
No rate limit is enforced today; page with limit ≤ 50 rather than looping on maximal payloads.

Getting started

Guides

Endpoints

Sync WhatsApp conversations

Concepts

Who sent what

Common requests

Incremental sync

Long conversations

Sample conversation

Notes and limits

​Concepts

​Who sent what

​Common requests

​Incremental sync

​Long conversations

​Sample conversation

​Notes and limits

Concepts

Who sent what

Common requests

Incremental sync

Long conversations

Sample conversation

Notes and limits