Messaging

LLM

Send, receive, and follow customer conversations across connected channels. For outbound messaging, choose an inbox, optionally upload media, send a message, then poll the message resource for delivery state when you are not using webhooks.

12 generated endpoints in this resource group.

Send flow

Choose the sender inbox with GET /inboxes.
Upload media first with POST /media/uploads when sending a file.
Send POST /messages with a recipient and one concrete content variant.
Poll GET /messages/{id} or conversation messages to follow delivery.

post/messages

Send a message#

Starts or continues a customer conversation by recipient. Choose an inbox first with `GET /inboxes`, optionally prepare WhatsApp template or media content, then send with a recipient that points to an existing conversation, a known contact, or a channel recipient. The response uses `202 Accepted`; poll `GET /messages/{id}` or the conversation messages endpoint to follow delivery state without webhooks.

Authorization

Scheme

bearerAuth

Allowed roles

owner
admin
agent

Send an outbound message. Conversation and channel recipients require message:create in conversation scope; contact recipients also resolve through contact:read.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
recipient
Type
MessageRecipient
Description
Required request attribute.
Name
content
Type
OutboundMessageContent
Description
Required request attribute.

Optional attributes

Name
expectedContext
Type
InboxActionContext
Description
Optional request attribute.
Name
inboxId
Type
string
Description
Sender inbox ID. Required for contact and phone recipients.
Name
contexts
Type
array<SendMessageContext>
Description
Optional request attribute.

Responses

Name
202
Type
application/json
Description
Message accepted for delivery
Name
default
Type
application/json
Description
Error

Related schemas

Request

POST/messages

curl -X POST "https://api.flownally.com/v1/messages" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "inboxId": "ibx_d7pi2efp0k7nba4e1mt0",
  "recipient": {
    "type": "phone",
    "phoneNumber": "+48123456789"
  },
  "content": {
    "type": "text",
    "text": {
      "body": "Hi Anna, your order is ready for pickup."
    }
  }
}'

Response

202application/json

{
  "message": {
    "id": "msg_d7pj3rljs4umccbo6tdg",
    "createdAt": "2026-04-30T10:36:00Z",
    "updatedAt": "2026-04-30T10:36:00Z",
    "tenantId": "tn_d7phk42ge9t9t6324f20",
    "conversationId": "cnv_d7pigoip4tfcdebp5mlg",
    "senderType": "user",
    "senderId": "usr_d7phosq4g7mv2l5b9l40",
    "content": {
      "type": "template",
      "template": {
        "name": "order_ready",
        "language": "en"
      }
    },
    "deliveryStatus": "pending"
  },
  "conversation": {
    "id": "cnv_d7pigoip4tfcdebp5mlg",
    "channel": "whatsapp",
    "externalId": "US.13491208655302741918",
    "inboxId": "ibx_d7pi2efp0k7nba4e1mt0",
    "name": "Anna Kowalska",
    "contactId": "con_d7pibvs6gljrc2pfdc1g",
    "contactName": "Anna Kowalska",
    "lastMessageAt": "2026-04-30T10:36:00Z",
    "lastMessagePreview": "order_ready",
    "lastMessageSender": "user"
  }
}

get/messages/{id}

Get message#

Returns delivery state and conversation context for polling integrations.

Authorization

Scheme

bearerAuth

Required scopes

conversation:read

Allowed roles

owner
admin
agent

Read a message through its conversation context.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Responses

Name
200
Type
application/json
Description
Message
Name
default
Type
application/json
Description
Error

Request

GETRequest

curl -X GET "https://api.flownally.com/v1/messages/{id}" \
  -H "Authorization: Bearer {token}"

Response

200application/json

{
  "message": {
    "id": "msg_d7pj3rljs4umccbo6tdg",
    "createdAt": "2026-04-30T10:36:00Z",
    "updatedAt": "2026-04-30T10:36:02Z",
    "tenantId": "tn_d7phk42ge9t9t6324f20",
    "conversationId": "cnv_d7pigoip4tfcdebp5mlg",
    "senderType": "user",
    "senderId": "usr_d7phosq4g7mv2l5b9l40",
    "content": {
      "type": "text",
      "text": {
        "body": "Hi Anna, your order is ready for pickup."
      }
    },
    "deliveryStatus": "delivered",
    "channelMessageId": "wamid.HBgLMjQxMjM0NTY3ODkVAgARGBI",
    "clientMessageId": "reply-4827-1"
  },
  "conversation": {
    "id": "cnv_d7pigoip4tfcdebp5mlg",
    "channel": "whatsapp",
    "externalId": "US.13491208655302741918",
    "inboxId": "ibx_d7pi2efp0k7nba4e1mt0",
    "name": "Anna Kowalska",
    "contactId": "con_d7pibvs6gljrc2pfdc1g",
    "contactName": "Anna Kowalska",
    "status": "open",
    "activeOwner": {
      "type": "user",
      "id": "usr_d7phtlmtf1g6fu9aj6jg"
    },
    "lastMessageAt": "2026-04-30T10:35:00Z",
    "lastMessagePreview": "Thanks, I will check it now.",
    "lastMessageSender": "customer"
  }
}

get/media/{mediaId}

Get message media#

Returns an authorized, short-lived download URL for Flownally-hosted media. Use `content.media.mediaId` from inbound messages, webhook payloads, WebSocket events, or upload responses as `{mediaId}`. Once ready, this response includes stored file metadata. Ingestion does not delay message creation or emit `message.updated`. Metadata already supplied on a message remains a compatibility snapshot; use this endpoint for the stored media metadata. A response with `ready: false` has no URL: - Without `failureCode`, ingestion is still in progress. Poll again with backoff. - With `failureCode`, the media failed permanently and will never become available. Stop polling.

Authorization

Scheme

bearerAuth

Required scopes

conversation:read

Allowed roles

owner
admin
agent

Get an authorized download URL for message media.

Required parameters

Name
mediaId
Type
path string
Description
Flownally media handle from `content.media.mediaId`.

Responses

Name
200
Type
application/json
Description
Media download URL, when the object is ready.
Name
default
Type
application/json
Description
Error

Related schemas

Request

GETRequest

curl -X GET "https://api.flownally.com/v1/media/{mediaId}" \
  -H "Authorization: Bearer {token}"

Response

200application/json

{
  "ready": true,
  "failureCode": "media_unavailable",
  "url": "https://example.com",
  "mimeType": "string",
  "filename": "string",
  "fileSize": 0
}

post/media/uploads

Upload message media#

Uploads a file and returns a `mediaId` handle for later message sends. Pass the handle as `content.media.mediaId` when sending media content.

Authorization

Scheme

bearerAuth

Required scopes

message:create

Allowed roles

owner
admin
agent

Upload media for a future message send.

Request body

Send a multipart/form-data body. The body is required for this operation.

Required attributes

Name
file
Type
string
Description
Image, document, video, or audio file to make available for message sending.

Responses

Name
201
Type
application/json
Description
Media uploaded
Name
default
Type
application/json
Description
Error

Related schemas

Request

POSTUpload file

curl -X POST "https://api.flownally.com/v1/media/uploads" \
  -H "Authorization: Bearer {token}" \
  -F "file=@invoice.pdf"

Response

201application/json

{
  "mediaId": "mda_d7pka1i9v5sfp2ud6chg",
  "mediaType": "document",
  "mimeType": "application/pdf",
  "filename": "invoice-4827.pdf",
  "fileSize": 184201
}

get/conversations

List conversations#

Returns conversations accessible to the authenticated user. Use this before polling message history or assigning work to a teammate.

Authorization

Scheme

bearerAuth

Required scopes

conversation:list

Allowed roles

owner
admin
agent

List conversations in the caller's conversation scope.

Optional parameters

Name
skipBucketCounts
Type
query boolean
Description
Omit bucket_counts to avoid recomputing aggregates on continuation pages. Defaults to false. Each request has its own snapshot.
Name
pageSize
Type
query integer
Description
Values above 100 are reduced to 100; 0 or omitted uses the default (50).
Name
pageToken
Type
query string
Description
Optional parameter.
Name
interacted
Type
query boolean
Description
Optional parameter.
Name
search
Type
query string
Description
Case-insensitive substring search across the conversation name and external identifier.
Name
conversationIds
Type
query array<string>
Description
Return explicit conversations by ID, preserving normal authorization scope.
Name
status
Type
query array<enum>
Description
Optional parameter.
Name
ownerType
Type
query array<enum>
Description
Optional parameter.
Name
sort
Type
query enum
Description
Optional parameter.
Name
bucket
Type
query enum
Description
Optional parameter.
Name
mine
Type
query boolean
Description
Restrict to open conversations owned by the authenticated human user.
Name
orderDirection
Type
query enum
Description
Optional parameter.

Responses

Name
200
Type
application/json
Description
List of conversations
Name
default
Type
application/json
Description
Error

Related schemas

Request

GETRequest

curl -G "https://api.flownally.com/v1/conversations" \
  -H "Authorization: Bearer {token}" \
  -d skipBucketCounts="{skipBucketCounts}" \
  -d pageSize="{pageSize}" \
  -d pageToken="{pageToken}" \
  -d interacted="{interacted}" \
  -d search="{search}" \
  -d conversationIds="{conversationIds}" \
  -d status="{status}" \
  -d ownerType="{ownerType}" \
  -d sort="{sort}" \
  -d bucket="{bucket}" \
  -d mine="{mine}" \
  -d orderDirection="{orderDirection}"

Response

200application/json

{
  "bucketCounts": {
    "open": 0,
    "automated": 0,
    "done": 0,
    "mine": 0
  },
  "conversations": [
    {
      "id": "cnv_d7pigoip4tfcdebp5mlg",
      "channel": "whatsapp",
      "externalId": "US.13491208655302741918",
      "inboxId": "ibx_d7pi2efp0k7nba4e1mt0",
      "name": "Anna Kowalska",
      "contactId": "con_d7pibvs6gljrc2pfdc1g",
      "contactName": "Anna Kowalska",
      "status": "open",
      "activeOwner": {
        "type": "user",
        "id": "usr_d7phtlmtf1g6fu9aj6jg"
      },
      "lastMessageAt": "2026-04-30T10:35:00Z",
      "lastMessagePreview": "Thanks, I will check it now.",
      "lastMessageSender": "customer"
    }
  ],
  "nextPageToken": "string"
}

get/conversations/{id}

Get conversation#

Returns the current conversation context, including the sendability window that tells whether an agent or bot can reply right now.

Authorization

Scheme

bearerAuth

Required scopes

conversation:read

Allowed roles

owner
admin
agent

Read a conversation in the caller's conversation scope.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Responses

Name
200
Type
application/json
Description
Conversation details
Name
default
Type
application/json
Description
Error

Related schemas

Request

GETRequest

curl -X GET "https://api.flownally.com/v1/conversations/{id}" \
  -H "Authorization: Bearer {token}"

Response

200application/json

{}

get/conversations/{id}/messages

List conversation messages#

Returns accessible message history ordered by createdAt descending, then id descending. Pass sessionId to retrieve only messages belonging to that session, including closed sessions. The session must belong to this conversation and be accessible to the caller; otherwise returns 404. With sessionId, the summary describes the selected session and its latest non-deleted message; conversation-wide messagingWindow, automationOutcome, and actionContext are omitted, and waitingSince is null. For an empty session, lastMessageAt is the session creation time and the preview is empty. Follow nextPageToken with the same conversation and sessionId. Page size may change between pages. Pages are separate snapshots; pagination does not freeze later messages or updates.

Authorization

Scheme

bearerAuth

Required scopes

conversation:read

Allowed roles

owner
admin
agent

List messages for a conversation in scope.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Optional parameters

Name
sessionId
Type
query string
Description
Filter by the session ID from a message or webhook. Omit for all accessible sessions.
Name
pageSize
Type
query integer
Description
Values above 100 are reduced to 100; 0 or omitted uses the default (50).
Name
pageToken
Type
query string
Description
Optional parameter.

Responses

Name
200
Type
application/json
Description
List of messages
Name
default
Type
application/json
Description
Error

Request

GETRequest

curl -G "https://api.flownally.com/v1/conversations/{id}/messages" \
  -H "Authorization: Bearer {token}" \
  -d sessionId="{sessionId}" \
  -d pageSize="{pageSize}" \
  -d pageToken="{pageToken}"

Response

200application/json

{
  "conversation": {},
  "messages": [
    {
      "id": "msg_d7pj3rljs4umccbo6tdg",
      "createdAt": "2026-04-30T10:36:00Z",
      "updatedAt": "2026-04-30T10:36:02Z",
      "tenantId": "tn_d7phk42ge9t9t6324f20",
      "conversationId": "cnv_d7pigoip4tfcdebp5mlg",
      "senderType": "user",
      "senderId": "usr_d7phosq4g7mv2l5b9l40",
      "content": {
        "type": "text",
        "text": {
          "body": "Hi Anna, your order is ready for pickup."
        }
      },
      "deliveryStatus": "delivered",
      "channelMessageId": "wamid.HBgLMjQxMjM0NTY3ODkVAgARGBI",
      "clientMessageId": "reply-4827-1"
    }
  ],
  "nextPageToken": "string"
}

post/conversations/{id}/messages

Send message in a conversation#

Sends a reply in an existing conversation. Pass `inboxId` when you want to choose the sender explicitly; otherwise Flownally uses the latest open session for that conversation. The response is returned as soon as the message is accepted, so poll the message resource to follow delivery state when you are not using webhooks.

Authorization

Scheme

bearerAuth

Required scopes

message:create

Allowed roles

owner
admin
agent

Send a message in a conversation in scope.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
content
Type
OutboundMessageContent
Description
Required request attribute.

Optional attributes

Name
expectedContext
Type
InboxActionContext
Description
Optional request attribute.
Name
inboxId
Type
string
Description
Sender inbox ID. Required for first-message sends.
Name
contexts
Type
array<SendMessageContext>
Description
Optional request attribute.

Responses

Name
202
Type
application/json
Description
Message accepted for delivery
Name
default
Type
application/json
Description
Error

Request

POST/conversations/{id}/messages

curl -X POST "https://api.flownally.com/v1/conversations/{id}/messages" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "content": {
    "type": "text",
    "text": {
      "body": "Thanks for reaching out. I am checking this now."
    }
  }
}'

Response

202application/json

{
  "message": {
    "id": "msg_d7pj3rljs4umccbo6tdg",
    "createdAt": "2026-04-30T10:36:00Z",
    "updatedAt": "2026-04-30T10:36:00Z",
    "tenantId": "tn_d7phk42ge9t9t6324f20",
    "conversationId": "cnv_d7pigoip4tfcdebp5mlg",
    "senderType": "user",
    "senderId": "usr_d7phosq4g7mv2l5b9l40",
    "content": {
      "type": "template",
      "template": {
        "name": "order_ready",
        "language": "en"
      }
    },
    "deliveryStatus": "pending"
  },
  "conversation": {
    "id": "cnv_d7pigoip4tfcdebp5mlg",
    "channel": "whatsapp",
    "externalId": "US.13491208655302741918",
    "inboxId": "ibx_d7pi2efp0k7nba4e1mt0",
    "name": "Anna Kowalska",
    "contactId": "con_d7pibvs6gljrc2pfdc1g",
    "contactName": "Anna Kowalska",
    "lastMessageAt": "2026-04-30T10:36:00Z",
    "lastMessagePreview": "order_ready",
    "lastMessageSender": "user"
  }
}

post/messages/{id}/reactions

Add or remove a reaction on a message#

Authorization

Scheme

bearerAuth

Required scopes

message:create

Allowed roles

owner
admin
agent

Add or remove a reaction in an authorized conversation context.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
emoji
Type
string
Description
Required request attribute.

Optional attributes

Name
removed
Type
boolean
Description
Optional request attribute.

Responses

Name
200
Type
application/json
Description
Reaction sent
Name
default
Type
application/json
Description
Error

Related schemas

Request

POSTRequest

curl -X POST "https://api.flownally.com/v1/messages/{id}/reactions" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "emoji": "string",
  "removed": true
}'

Response

200application/json

{
  "reaction": {
    "id": "string",
    "messageId": "string",
    "senderType": "string",
    "senderId": "string",
    "emoji": "string",
    "createdAt": "2026-04-27T00:00:00.000Z"
  }
}

post/conversations/{id}:reassign

Reassign conversation#

Reassigns a conversation to a different user

Authorization

Scheme

bearerAuth

Required scopes

conversation:assign

Allowed roles

owner
admin
agent

Reassign a conversation in scope.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
userId
Type
string
Description
Required request attribute.

Responses

Name
204
Description
Conversation reassigned
Name
default
Type
application/json
Description
Error

Related schemas

Request

POSTRequest

curl -X POST "https://api.flownally.com/v1/conversations/{id}:reassign" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "string"
}'

Response

204

204 Conversation reassigned

post/conversations/{id}:markRead

Mark conversation as read#

Records messages through the specified message as read for the authenticated reader. The latest eligible incoming customer message at or before the boundary is acknowledged asynchronously on supported channels on a best-effort basis. The boundary may be outgoing. Success confirms local read state, not customer notification or display. Unsupported channels, scheduling failures, and receipt delivery failures do not undo local read state.

Authorization

Scheme

bearerAuth

Required scopes

conversation:read

Allowed roles

owner
admin
agent

Mark a conversation in scope as read.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
lastMessageId
Type
string
Description
Required request attribute.

Responses

Name
200
Type
application/json
Description
Conversation marked as read
Name
default
Type
application/json
Description
Error

Related schemas

Request

POSTRequest

curl -X POST "https://api.flownally.com/v1/conversations/{id}:markRead" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "lastMessageId": "string"
}'

Response

200application/json

{
  "id": "cnv_d7pigoip4tfcdebp5mlg",
  "channel": "whatsapp",
  "externalId": "US.13491208655302741918",
  "inboxId": "ibx_d7pi2efp0k7nba4e1mt0",
  "name": "Anna Kowalska",
  "contactId": "con_d7pibvs6gljrc2pfdc1g",
  "contactName": "Anna Kowalska",
  "status": "open",
  "activeOwner": {
    "type": "user",
    "id": "usr_d7phtlmtf1g6fu9aj6jg"
  },
  "lastMessageAt": "2026-04-30T10:35:00Z",
  "lastMessagePreview": "Thanks, I will check it now.",
  "lastMessageSender": "customer"
}

post/conversations/{id}:close

Close conversation#

Closes the conversation's open session and returns the updated conversation. Returns `404` when the conversation has no open session, and `409` with code `messaging_inbox_context_changed` when `expectedContext` no longer matches the conversation. A closed session is never reopened: the next message starts a new session in the same conversation. Sessions also close automatically, depending on who owns them: - Chatbot, API key (`service_account`) or connected inbox (`inbox`): 1 hour after the owner's latest successful reply if the customer hasn't written since; otherwise 7 days after the customer's latest message. - Human agent (`user`): 7 days after the latest successful agent reply if the customer hasn't written since. A session waiting for an agent's reply isn't closed automatically. - Journey: 7 days after the journey's latest successful message while the customer hasn't replied. - Unassigned sessions aren't closed automatically. A reply counts as successful once its `deliveryStatus` is `sent`, `delivered` or `read`.

Authorization

Scheme

bearerAuth

Required scopes

conversation:close

Allowed roles

owner
admin
agent

Close a conversation in scope.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Request body

Send a application/json body. The body is optional for this operation.

Optional attributes

Name
expectedContext
Type
InboxActionContext
Description
Optional request attribute.

Responses

Name
200
Type
application/json
Description
Conversation closed
Name
default
Type
application/json
Description
Error

Related schemas

Request

POSTRequest

curl -X POST "https://api.flownally.com/v1/conversations/{id}:close" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "expectedContext": {
    "sessionId": "string",
    "ownerType": "string",
    "ownerId": "string",
    "lastSubstantiveMessageId": "string",
    "substantiveVersion": "string"
  }
}'

Response

200application/json

{}

Messaging

LLM

View as Markdown

Open llms.txt

12 generated endpoints in this resource group.

Send flow

Choose the sender inbox with GET /inboxes.
Upload media first with POST /media/uploads when sending a file.
Send POST /messages with a recipient and one concrete content variant.
Poll GET /messages/{id} or conversation messages to follow delivery.

post/messages

Send a message#

Authorization

Scheme

bearerAuth

Allowed roles

owner
admin
agent

Send an outbound message. Conversation and channel recipients require message:create in conversation scope; contact recipients also resolve through contact:read.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
recipient
Type
MessageRecipient
Description
Required request attribute.
Name
content
Type
OutboundMessageContent
Description
Required request attribute.

Optional attributes

Name
expectedContext
Type
InboxActionContext
Description
Optional request attribute.
Name
inboxId
Type
string
Description
Sender inbox ID. Required for contact and phone recipients.
Name
contexts
Type
array<SendMessageContext>
Description
Optional request attribute.

Responses

Name
202
Type
application/json
Description
Message accepted for delivery
Name
default
Type
application/json
Description
Error

Related schemas

Request

POST/messages

curl -X POST "https://api.flownally.com/v1/messages" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "inboxId": "ibx_d7pi2efp0k7nba4e1mt0",
  "recipient": {
    "type": "phone",
    "phoneNumber": "+48123456789"
  },
  "content": {
    "type": "text",
    "text": {
      "body": "Hi Anna, your order is ready for pickup."
    }
  }
}'

Response

202application/json

{
  "message": {
    "id": "msg_d7pj3rljs4umccbo6tdg",
    "createdAt": "2026-04-30T10:36:00Z",
    "updatedAt": "2026-04-30T10:36:00Z",
    "tenantId": "tn_d7phk42ge9t9t6324f20",
    "conversationId": "cnv_d7pigoip4tfcdebp5mlg",
    "senderType": "user",
    "senderId": "usr_d7phosq4g7mv2l5b9l40",
    "content": {
      "type": "template",
      "template": {
        "name": "order_ready",
        "language": "en"
      }
    },
    "deliveryStatus": "pending"
  },
  "conversation": {
    "id": "cnv_d7pigoip4tfcdebp5mlg",
    "channel": "whatsapp",
    "externalId": "US.13491208655302741918",
    "inboxId": "ibx_d7pi2efp0k7nba4e1mt0",
    "name": "Anna Kowalska",
    "contactId": "con_d7pibvs6gljrc2pfdc1g",
    "contactName": "Anna Kowalska",
    "lastMessageAt": "2026-04-30T10:36:00Z",
    "lastMessagePreview": "order_ready",
    "lastMessageSender": "user"
  }
}

get/messages/{id}

Get message#

Returns delivery state and conversation context for polling integrations.

Authorization

Scheme

bearerAuth

Required scopes

conversation:read

Allowed roles

owner
admin
agent

Read a message through its conversation context.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Responses

Name
200
Type
application/json
Description
Message
Name
default
Type
application/json
Description
Error

Request

GETRequest

curl -X GET "https://api.flownally.com/v1/messages/{id}" \
  -H "Authorization: Bearer {token}"

Response

200application/json

{
  "message": {
    "id": "msg_d7pj3rljs4umccbo6tdg",
    "createdAt": "2026-04-30T10:36:00Z",
    "updatedAt": "2026-04-30T10:36:02Z",
    "tenantId": "tn_d7phk42ge9t9t6324f20",
    "conversationId": "cnv_d7pigoip4tfcdebp5mlg",
    "senderType": "user",
    "senderId": "usr_d7phosq4g7mv2l5b9l40",
    "content": {
      "type": "text",
      "text": {
        "body": "Hi Anna, your order is ready for pickup."
      }
    },
    "deliveryStatus": "delivered",
    "channelMessageId": "wamid.HBgLMjQxMjM0NTY3ODkVAgARGBI",
    "clientMessageId": "reply-4827-1"
  },
  "conversation": {
    "id": "cnv_d7pigoip4tfcdebp5mlg",
    "channel": "whatsapp",
    "externalId": "US.13491208655302741918",
    "inboxId": "ibx_d7pi2efp0k7nba4e1mt0",
    "name": "Anna Kowalska",
    "contactId": "con_d7pibvs6gljrc2pfdc1g",
    "contactName": "Anna Kowalska",
    "status": "open",
    "activeOwner": {
      "type": "user",
      "id": "usr_d7phtlmtf1g6fu9aj6jg"
    },
    "lastMessageAt": "2026-04-30T10:35:00Z",
    "lastMessagePreview": "Thanks, I will check it now.",
    "lastMessageSender": "customer"
  }
}

get/media/{mediaId}

Get message media#

Authorization

Scheme

bearerAuth

Required scopes

conversation:read

Allowed roles

owner
admin
agent

Get an authorized download URL for message media.

Required parameters

Name
mediaId
Type
path string
Description
Flownally media handle from `content.media.mediaId`.

Responses

Name
200
Type
application/json
Description
Media download URL, when the object is ready.
Name
default
Type
application/json
Description
Error

Related schemas

Request

GETRequest

curl -X GET "https://api.flownally.com/v1/media/{mediaId}" \
  -H "Authorization: Bearer {token}"

Response

200application/json

{
  "ready": true,
  "failureCode": "media_unavailable",
  "url": "https://example.com",
  "mimeType": "string",
  "filename": "string",
  "fileSize": 0
}

post/media/uploads

Upload message media#

Uploads a file and returns a `mediaId` handle for later message sends. Pass the handle as `content.media.mediaId` when sending media content.

Authorization

Scheme

bearerAuth

Required scopes

message:create

Allowed roles

owner
admin
agent

Upload media for a future message send.

Request body

Send a multipart/form-data body. The body is required for this operation.

Required attributes

Name
file
Type
string
Description
Image, document, video, or audio file to make available for message sending.

Responses

Name
201
Type
application/json
Description
Media uploaded
Name
default
Type
application/json
Description
Error

Related schemas

Request

POSTUpload file

curl -X POST "https://api.flownally.com/v1/media/uploads" \
  -H "Authorization: Bearer {token}" \
  -F "file=@invoice.pdf"

Response

201application/json

{
  "mediaId": "mda_d7pka1i9v5sfp2ud6chg",
  "mediaType": "document",
  "mimeType": "application/pdf",
  "filename": "invoice-4827.pdf",
  "fileSize": 184201
}

get/conversations

List conversations#

Returns conversations accessible to the authenticated user. Use this before polling message history or assigning work to a teammate.

Authorization

Scheme

bearerAuth

Required scopes

conversation:list

Allowed roles

owner
admin
agent

List conversations in the caller's conversation scope.

Optional parameters

Name
skipBucketCounts
Type
query boolean
Description
Omit bucket_counts to avoid recomputing aggregates on continuation pages. Defaults to false. Each request has its own snapshot.
Name
pageSize
Type
query integer
Description
Values above 100 are reduced to 100; 0 or omitted uses the default (50).
Name
pageToken
Type
query string
Description
Optional parameter.
Name
interacted
Type
query boolean
Description
Optional parameter.
Name
search
Type
query string
Description
Case-insensitive substring search across the conversation name and external identifier.
Name
conversationIds
Type
query array<string>
Description
Return explicit conversations by ID, preserving normal authorization scope.
Name
status
Type
query array<enum>
Description
Optional parameter.
Name
ownerType
Type
query array<enum>
Description
Optional parameter.
Name
sort
Type
query enum
Description
Optional parameter.
Name
bucket
Type
query enum
Description
Optional parameter.
Name
mine
Type
query boolean
Description
Restrict to open conversations owned by the authenticated human user.
Name
orderDirection
Type
query enum
Description
Optional parameter.

Responses

Name
200
Type
application/json
Description
List of conversations
Name
default
Type
application/json
Description
Error

Related schemas

Request

GETRequest

curl -G "https://api.flownally.com/v1/conversations" \
  -H "Authorization: Bearer {token}" \
  -d skipBucketCounts="{skipBucketCounts}" \
  -d pageSize="{pageSize}" \
  -d pageToken="{pageToken}" \
  -d interacted="{interacted}" \
  -d search="{search}" \
  -d conversationIds="{conversationIds}" \
  -d status="{status}" \
  -d ownerType="{ownerType}" \
  -d sort="{sort}" \
  -d bucket="{bucket}" \
  -d mine="{mine}" \
  -d orderDirection="{orderDirection}"

Response

200application/json

{
  "bucketCounts": {
    "open": 0,
    "automated": 0,
    "done": 0,
    "mine": 0
  },
  "conversations": [
    {
      "id": "cnv_d7pigoip4tfcdebp5mlg",
      "channel": "whatsapp",
      "externalId": "US.13491208655302741918",
      "inboxId": "ibx_d7pi2efp0k7nba4e1mt0",
      "name": "Anna Kowalska",
      "contactId": "con_d7pibvs6gljrc2pfdc1g",
      "contactName": "Anna Kowalska",
      "status": "open",
      "activeOwner": {
        "type": "user",
        "id": "usr_d7phtlmtf1g6fu9aj6jg"
      },
      "lastMessageAt": "2026-04-30T10:35:00Z",
      "lastMessagePreview": "Thanks, I will check it now.",
      "lastMessageSender": "customer"
    }
  ],
  "nextPageToken": "string"
}

get/conversations/{id}

Get conversation#

Returns the current conversation context, including the sendability window that tells whether an agent or bot can reply right now.

Authorization

Scheme

bearerAuth

Required scopes

conversation:read

Allowed roles

owner
admin
agent

Read a conversation in the caller's conversation scope.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Responses

Name
200
Type
application/json
Description
Conversation details
Name
default
Type
application/json
Description
Error

Related schemas

Request

GETRequest

curl -X GET "https://api.flownally.com/v1/conversations/{id}" \
  -H "Authorization: Bearer {token}"

Response

200application/json

{}

get/conversations/{id}/messages

List conversation messages#

Authorization

Scheme

bearerAuth

Required scopes

conversation:read

Allowed roles

owner
admin
agent

List messages for a conversation in scope.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Optional parameters

Name
sessionId
Type
query string
Description
Filter by the session ID from a message or webhook. Omit for all accessible sessions.
Name
pageSize
Type
query integer
Description
Values above 100 are reduced to 100; 0 or omitted uses the default (50).
Name
pageToken
Type
query string
Description
Optional parameter.

Responses

Name
200
Type
application/json
Description
List of messages
Name
default
Type
application/json
Description
Error

Request

GETRequest

curl -G "https://api.flownally.com/v1/conversations/{id}/messages" \
  -H "Authorization: Bearer {token}" \
  -d sessionId="{sessionId}" \
  -d pageSize="{pageSize}" \
  -d pageToken="{pageToken}"

Response

200application/json

{
  "conversation": {},
  "messages": [
    {
      "id": "msg_d7pj3rljs4umccbo6tdg",
      "createdAt": "2026-04-30T10:36:00Z",
      "updatedAt": "2026-04-30T10:36:02Z",
      "tenantId": "tn_d7phk42ge9t9t6324f20",
      "conversationId": "cnv_d7pigoip4tfcdebp5mlg",
      "senderType": "user",
      "senderId": "usr_d7phosq4g7mv2l5b9l40",
      "content": {
        "type": "text",
        "text": {
          "body": "Hi Anna, your order is ready for pickup."
        }
      },
      "deliveryStatus": "delivered",
      "channelMessageId": "wamid.HBgLMjQxMjM0NTY3ODkVAgARGBI",
      "clientMessageId": "reply-4827-1"
    }
  ],
  "nextPageToken": "string"
}

post/conversations/{id}/messages

Send message in a conversation#

Authorization

Scheme

bearerAuth

Required scopes

message:create

Allowed roles

owner
admin
agent

Send a message in a conversation in scope.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
content
Type
OutboundMessageContent
Description
Required request attribute.

Optional attributes

Name
expectedContext
Type
InboxActionContext
Description
Optional request attribute.
Name
inboxId
Type
string
Description
Sender inbox ID. Required for first-message sends.
Name
contexts
Type
array<SendMessageContext>
Description
Optional request attribute.

Responses

Name
202
Type
application/json
Description
Message accepted for delivery
Name
default
Type
application/json
Description
Error

Request

POST/conversations/{id}/messages

curl -X POST "https://api.flownally.com/v1/conversations/{id}/messages" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "content": {
    "type": "text",
    "text": {
      "body": "Thanks for reaching out. I am checking this now."
    }
  }
}'

Response

202application/json

{
  "message": {
    "id": "msg_d7pj3rljs4umccbo6tdg",
    "createdAt": "2026-04-30T10:36:00Z",
    "updatedAt": "2026-04-30T10:36:00Z",
    "tenantId": "tn_d7phk42ge9t9t6324f20",
    "conversationId": "cnv_d7pigoip4tfcdebp5mlg",
    "senderType": "user",
    "senderId": "usr_d7phosq4g7mv2l5b9l40",
    "content": {
      "type": "template",
      "template": {
        "name": "order_ready",
        "language": "en"
      }
    },
    "deliveryStatus": "pending"
  },
  "conversation": {
    "id": "cnv_d7pigoip4tfcdebp5mlg",
    "channel": "whatsapp",
    "externalId": "US.13491208655302741918",
    "inboxId": "ibx_d7pi2efp0k7nba4e1mt0",
    "name": "Anna Kowalska",
    "contactId": "con_d7pibvs6gljrc2pfdc1g",
    "contactName": "Anna Kowalska",
    "lastMessageAt": "2026-04-30T10:36:00Z",
    "lastMessagePreview": "order_ready",
    "lastMessageSender": "user"
  }
}

post/messages/{id}/reactions

Add or remove a reaction on a message#

Authorization

Scheme

bearerAuth

Required scopes

message:create

Allowed roles

owner
admin
agent

Add or remove a reaction in an authorized conversation context.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
emoji
Type
string
Description
Required request attribute.

Optional attributes

Name
removed
Type
boolean
Description
Optional request attribute.

Responses

Name
200
Type
application/json
Description
Reaction sent
Name
default
Type
application/json
Description
Error

Related schemas

Request

POSTRequest

curl -X POST "https://api.flownally.com/v1/messages/{id}/reactions" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "emoji": "string",
  "removed": true
}'

Response

200application/json

{
  "reaction": {
    "id": "string",
    "messageId": "string",
    "senderType": "string",
    "senderId": "string",
    "emoji": "string",
    "createdAt": "2026-04-27T00:00:00.000Z"
  }
}

post/conversations/{id}:reassign

Reassign conversation#

Reassigns a conversation to a different user

Authorization

Scheme

bearerAuth

Required scopes

conversation:assign

Allowed roles

owner
admin
agent

Reassign a conversation in scope.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
userId
Type
string
Description
Required request attribute.

Responses

Name
204
Description
Conversation reassigned
Name
default
Type
application/json
Description
Error

Related schemas

Request

POSTRequest

curl -X POST "https://api.flownally.com/v1/conversations/{id}:reassign" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "string"
}'

Response

204

204 Conversation reassigned

post/conversations/{id}:markRead

Mark conversation as read#

Authorization

Scheme

bearerAuth

Required scopes

conversation:read

Allowed roles

owner
admin
agent

Mark a conversation in scope as read.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Request body

Send a application/json body. The body is required for this operation.

Required attributes

Name
lastMessageId
Type
string
Description
Required request attribute.

Responses

Name
200
Type
application/json
Description
Conversation marked as read
Name
default
Type
application/json
Description
Error

Related schemas

Request

POSTRequest

curl -X POST "https://api.flownally.com/v1/conversations/{id}:markRead" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "lastMessageId": "string"
}'

Response

200application/json

{
  "id": "cnv_d7pigoip4tfcdebp5mlg",
  "channel": "whatsapp",
  "externalId": "US.13491208655302741918",
  "inboxId": "ibx_d7pi2efp0k7nba4e1mt0",
  "name": "Anna Kowalska",
  "contactId": "con_d7pibvs6gljrc2pfdc1g",
  "contactName": "Anna Kowalska",
  "status": "open",
  "activeOwner": {
    "type": "user",
    "id": "usr_d7phtlmtf1g6fu9aj6jg"
  },
  "lastMessageAt": "2026-04-30T10:35:00Z",
  "lastMessagePreview": "Thanks, I will check it now.",
  "lastMessageSender": "customer"
}

post/conversations/{id}:close

Close conversation#

Authorization

Scheme

bearerAuth

Required scopes

conversation:close

Allowed roles

owner
admin
agent

Close a conversation in scope.

Required parameters

Name
id
Type
path string
Description
Required parameter.

Request body

Send a application/json body. The body is optional for this operation.

Optional attributes

Name
expectedContext
Type
InboxActionContext
Description
Optional request attribute.

Responses

Name
200
Type
application/json
Description
Conversation closed
Name
default
Type
application/json
Description
Error

Related schemas

Request

POSTRequest

curl -X POST "https://api.flownally.com/v1/conversations/{id}:close" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "expectedContext": {
    "sessionId": "string",
    "ownerType": "string",
    "ownerId": "string",
    "lastSubstantiveMessageId": "string",
    "substantiveVersion": "string"
  }
}'

Response

200application/json

{}