NatiqDocs

Appearance

Open Natiq

Messages

Read a conversation's timeline, send replies, leave private notes and set the conversation language.

Updated 7 Nov 2026

The messages inside a conversation, and the internal notes agents leave beside them. The timeline merges both, newest first. Replies you send go out through the channel the conversation arrived on, so a WhatsApp conversation sends over WhatsApp.

Endpoints

GET/conversations/{conversationId}/timelineList a conversation’s timelinePOST/conversations/{conversationId}/messagesSend a messagePOST/conversations/{conversationId}/notesAdd a private notePOST/conversations/{conversationId}/seenMark a conversation as seenPUT/conversations/{conversationId}/languageSet a conversation’s language

The message object

One entry of the timeline: a customer message, an agent or bot reply, a system event or a private note.

Attributes

  • idinteger
    Message ID. Messages and private notes are numbered independently, so a note and a message in one conversation can share an id — tell them apart with privateNote.
  • conversationIdinteger
    The conversation this entry belongs to.
  • senderTypestring
    Who wrote it.
    One of: CONTACTAGENTBOTSYSTEMCAMPAIGN
  • messageTypestring
    The kind of content: TEXT, IMAGE, AUDIO, VIDEO, DOCUMENT, STICKER, LOCATION, CONTACTS, INTERACTIVE, REACTION or TEMPLATE. Private notes use PRIVATE_NOTE.
  • channelTypestringnullable
    Channel it travelled on, e.g. WHATSAPP.
  • contentstringnullable
    The text, when the message has any.
  • contentJsonstringnullable
    Structured content for non-text messages, as a serialised JSON string. Parse it before use. (Requests take a real JSON value instead.)
  • statusstringnullable
    Delivery state. PENDING means queued but not yet accepted by the channel.
    One of: RECEIVEDPENDINGSENTDELIVEREDREADFAILED
  • providerMessageIdstringnullable
    The channel provider’s own ID for the message.
  • privateNoteboolean
    Always present: false on a message, true on an internal note. Notes are never delivered to the customer. A note has senderType AGENT, channelType INTERNAL, contentJson "{}" and status SENT.
  • originTypestringnullable
    What produced the entry, such as AGENT for a note or HANDOFF for a hand-over message. Free-form; treat unknown values as possible.
  • originIdintegernullable
    The ID of that origin, when it has one.
  • originKindstringnullable
    Set when a macro, an automation rule or auto-resolve wrote the entry; otherwise null.
    One of: MACROAUTOMATION_RULEAUTO_RESOLVE
  • sourceIdintegernullable
    The ID of the macro, rule or other source named by originKind.
  • errorMessagestringnullable
    Why delivery failed, when status is FAILED.
  • noteKindstringnullable
    TRANSFER_NOTE for a handover note posted with a transfer; otherwise null.
    One of: TRANSFER_NOTE
  • transferEventIdintegernullable
    The transfer a TRANSFER_NOTE belongs to.
  • replyToMessageIdintegernullable
    The message this one quotes, for both an agent’s quote-reply and a customer’s WhatsApp reply.
  • campaignIdintegernullable
    The campaign that sent it, for CAMPAIGN messages.
  • attachmentsarray<object>
    Files on the message, in one shape for every channel.
  • createdAtstringnullable
    When it was written (ISO 8601).
The message object
json
{
  "id": 90417,
  "conversationId": 4388,
  "senderType": "CONTACT",
  "messageType": "TEXT",
  "channelType": "WHATSAPP",
  "content": "مرحبا، أريد تغيير موعد الفاتورة",
  "contentJson": null,
  "status": "RECEIVED",
  "providerMessageId": "wamid.HBgLOTYyNzkxMjM0NTY3FQIAEhgg",
  "privateNote": false,
  "originType": null,
  "originId": null,
  "originKind": null,
  "sourceId": null,
  "errorMessage": null,
  "noteKind": null,
  "transferEventId": null,
  "replyToMessageId": null,
  "campaignId": null,
  "attachments": [],
  "createdAt": "2026-11-06T09:41:12Z"
}

List a conversation’s timeline

Returns messages and private notes, newest first, as a plain array. Keyset paginated: pass the smallest id of the page you have as afterId to get older entries. Notes and messages are merged by time, so a page can hold fewer messages than size. Notes are numbered separately from messages, so take that id from the oldest entry that is not a private note.

Requires liveagent.conversations:read Keyset paginated

Path parameters

  • conversationIdintegerrequired
    The conversation’s id — the conversationId on a ticket.

Query parameters

  • afterIdinteger
    Return entries older than this ID. Pass the id of the oldest entry that is not a private note (privateNote: false), because note IDs come from a separate sequence. 0 or omitted returns the newest.
  • sizeinteger
    Entries per page. Defaults to 50, clamped to 1–100.

Returns

200The message object.

Errors

  • 404CONVERSATION_NOT_FOUNDNo conversation with this ID in your organisation.
bash
curl -X GET "https://api.cx.na6iq.com/api/v1/conversations/42/timeline?size=25" \
  -H "Authorization: Bearer $NATIQ_TOKEN"
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/conversations/42/timeline?size=25', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
  },
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
const data = await res.json()
python
import os, requests

res = requests.get(
    "https://api.cx.na6iq.com/api/v1/conversations/42/timeline?size=25",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
)
res.raise_for_status()
data = res.json()
Response200
json
[
  {
    "id": 90418,
    "conversationId": 4388,
    "senderType": "AGENT",
    "messageType": "TEXT",
    "channelType": "WHATSAPP",
    "content": "أهلاً ليلى، يسعدني مساعدتك. أي موعد تفضّلين؟",
    "contentJson": null,
    "status": "SENT",
    "providerMessageId": "wamid.HBgLOTYyNzkxMjM0NTY3FQIAEhggQ0E",
    "privateNote": false,
    "originType": "AGENT",
    "originId": 214,
    "originKind": null,
    "sourceId": null,
    "errorMessage": null,
    "noteKind": null,
    "transferEventId": null,
    "replyToMessageId": null,
    "campaignId": null,
    "attachments": [],
    "createdAt": "2026-11-06T09:42:03Z"
  },
  {
    "id": 90417,
    "conversationId": 4388,
    "senderType": "CONTACT",
    "messageType": "TEXT",
    "channelType": "WHATSAPP",
    "content": "مرحبا، أريد تغيير موعد الفاتورة",
    "contentJson": null,
    "status": "RECEIVED",
    "providerMessageId": "wamid.HBgLOTYyNzkxMjM0NTY3FQIAEhgg",
    "privateNote": false,
    "originType": null,
    "originId": null,
    "originKind": null,
    "sourceId": null,
    "errorMessage": null,
    "noteKind": null,
    "transferEventId": null,
    "replyToMessageId": null,
    "campaignId": null,
    "attachments": [],
    "createdAt": "2026-11-06T09:41:12Z"
  }
]

Send a message

Sends an agent reply. The reply is stored first and then handed to the channel, so the response status is usually PENDING (the message is sent after the response) and may later become SENT or FAILED. The response also carries assignedToOther: { agentId, displayName } when another agent holds the ticket, else null. Send an idempotencyKey (one is generated when blank, but then a retry cannot be de-duplicated) and reuse the same one when you retry — the backend de-duplicates per organisation, so a retry never sends twice. TEXT needs non-blank content; media types need contentJson.link or contentJson.id. To send an approved WhatsApp template, pass template with no content or contentJson.

Requires liveagent.conversations:write

Path parameters

  • conversationIdintegerrequired
    The conversation’s id — the conversationId on a ticket.

Request body

  • idempotencyKeystring
    Recommended. A unique key for this send, e.g. a UUID. Reuse it on retry. Generated when blank.
  • messageTypestring
    The kind of message. Defaults to TEXT.
    One of: TEXTIMAGEAUDIOVIDEODOCUMENTSTICKERLOCATIONCONTACTSINTERACTIVEREACTIONTEMPLATE
  • contentstring
    The text of a TEXT message.
  • contentJsonobject
    Structured content, as a real JSON value (not a string). For media: { "type": "image", "link": "https://…", "caption": "…" }.
  • replyToMessageIdintegernullable
    Quote an earlier message from the same conversation.
  • templateobject
    Send an approved WhatsApp template.

Returns

201The message object.

Errors

  • 400VALIDATION_FAILEDA required field is missing, or `replyToMessageId` is not in this conversation.
  • 404CONVERSATION_NOT_FOUNDNo conversation with this ID in your organisation.
  • 404INBOX_NOT_FOUNDThe conversation’s queue no longer exists.
  • 409NOT_ASSIGNEEThe queue lets only the assignee reply, and you are not the assignee. `error.data` is `{ assignedAgentId, assignedAgentName, version }`.
  • 409DUPLICATE_REPLYA colleague just sent the same text. `error.data` is `{ outboundMessageId, messageId, sentByUserId, sentByName, sentAt }`.
  • 409TEMPLATE_REQUIREDThe WhatsApp 24-hour window is closed; send an approved template instead. `error.data` is `{ channelType, lastInboundAt, freeFormUntil }`.
  • 502CHANNEL_SEND_FAILEDThe channel provider refused the send.
bash
curl -X POST "https://api.cx.na6iq.com/api/v1/conversations/42/messages" \
  -H "Authorization: Bearer $NATIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "idempotencyKey": "2f6b8f0e-5c2a-4e53-9d5c-7a9f0b1a6c11",
  "messageType": "TEXT",
  "content": "أهلاً ليلى، يسعدني مساعدتك. أي موعد تفضّلين؟"
}'
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/conversations/42/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "idempotencyKey": "2f6b8f0e-5c2a-4e53-9d5c-7a9f0b1a6c11",
    "messageType": "TEXT",
    "content": "أهلاً ليلى، يسعدني مساعدتك. أي موعد تفضّلين؟"
  }),
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
const data = await res.json()
python
import os, requests

res = requests.post(
    "https://api.cx.na6iq.com/api/v1/conversations/42/messages",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
    json={
      "idempotencyKey": "2f6b8f0e-5c2a-4e53-9d5c-7a9f0b1a6c11",
      "messageType": "TEXT",
      "content": "أهلاً ليلى، يسعدني مساعدتك. أي موعد تفضّلين؟"
    },
)
res.raise_for_status()
data = res.json()
Response201
json
{
  "id": 90418,
  "conversationId": 4388,
  "senderType": "AGENT",
  "messageType": "TEXT",
  "content": "أهلاً ليلى، يسعدني مساعدتك. أي موعد تفضّلين؟",
  "contentJson": null,
  "status": "PENDING",
  "providerMessageId": null,
  "createdAt": "2026-11-06T09:42:03Z",
  "replyToMessageId": null,
  "assignedToOther": null
}

Add a private note

Leaves an internal note for your team on the conversation. Notes are stored and shown in the timeline, and are never delivered to the customer.

Requires liveagent.conversations:write

Path parameters

  • conversationIdintegerrequired
    The conversation’s id — the conversationId on a ticket.

Request body

  • contentstringrequired
    The note text.

Returns

201The message object.

Errors

  • 400VALIDATION_FAILED`content` is blank.
  • 404CONVERSATION_NOT_FOUNDNo conversation with this ID in your organisation.
bash
curl -X POST "https://api.cx.na6iq.com/api/v1/conversations/42/notes" \
  -H "Authorization: Bearer $NATIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "content": "Customer is on the Gold plan — approve the date change."
}'
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/conversations/42/notes', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "content": "Customer is on the Gold plan — approve the date change."
  }),
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
const data = await res.json()
python
import os, requests

res = requests.post(
    "https://api.cx.na6iq.com/api/v1/conversations/42/notes",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
    json={
      "content": "Customer is on the Gold plan — approve the date change."
    },
)
res.raise_for_status()
data = res.json()
Response201
json
{
  "id": 733,
  "conversationId": 4388,
  "ticketId": 5120,
  "authorUserId": 214,
  "content": "Customer is on the Gold plan — approve the date change.",
  "originKind": null,
  "sourceId": null,
  "createdAt": "2026-11-06T09:43:40Z"
}

Mark a conversation as seen

Records the calling agent’s last-seen point, which clears the conversation’s unread count for that agent. No request body.

Requires liveagent.conversations:read

Path parameters

  • conversationIdintegerrequired
    The conversation’s id — the conversationId on a ticket.

Returns

200The new read position. `lastSeenMessageId` is `null` when the conversation has no messages.

Errors

  • 404CONVERSATION_NOT_FOUNDNo conversation with this ID in your organisation.
  • 404AGENT_NOT_FOUNDThe caller has no agent profile.
bash
curl -X POST "https://api.cx.na6iq.com/api/v1/conversations/42/seen" \
  -H "Authorization: Bearer $NATIQ_TOKEN"
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/conversations/42/seen', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
  },
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
const data = await res.json()
python
import os, requests

res = requests.post(
    "https://api.cx.na6iq.com/api/v1/conversations/42/seen",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
)
res.raise_for_status()
data = res.json()
Response200
json
{
  "conversationId": 4388,
  "lastSeenAt": "2026-11-06T09:44:10Z",
  "lastSeenMessageId": 90418,
  "unreadCount": 0
}

Set a conversation’s language

Overrides the language detected for the conversation. Send null to clear the override so detection takes over again. Routing rules read this language, so it is a routing correction, not only a label.

Requires liveagent.conversations:write

Path parameters

  • conversationIdintegerrequired
    The conversation’s id — the conversationId on a ticket.

Request body

  • languagestringnullable
    ar, en or other (case-insensitive). null or blank clears the override.

Returns

200The message object.

Errors

  • 400INVALID_REQUEST`language` is not `ar`, `en` or `other`.
  • 404CONVERSATION_NOT_FOUNDNo conversation with this ID in your organisation.
bash
curl -X PUT "https://api.cx.na6iq.com/api/v1/conversations/42/language" \
  -H "Authorization: Bearer $NATIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "language": "ar"
}'
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/conversations/42/language', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "language": "ar"
  }),
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
const data = await res.json()
python
import os, requests

res = requests.put(
    "https://api.cx.na6iq.com/api/v1/conversations/42/language",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
    json={
      "language": "ar"
    },
)
res.raise_for_status()
data = res.json()
Response200
json
{
  "conversationId": 4388,
  "language": "ar",
  "languageSource": "MANUAL"
}