Skip to main content
FlownallyAPI Docs

Messaging

LLM
View as Markdown
Open llms.txt

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.

11 generated endpoints in this resource group.

Send flow

  1. Choose the sender inbox with GET /inboxes.
  2. Upload media first with POST /media/uploads when sending a file.
  3. Send POST /messages with a recipient and one concrete content variant.
  4. 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

Required scopes

  • message:create

Allowed roles

  • owner
  • admin
  • agent

Send an outbound message in an authorized conversation context.

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
    MessageContent
    Description
    Required request attribute.

Optional attributes

  • Name
    inboxId
    Type
    string
    Description
    Sender inbox ID. Required for first-message sends to a channel recipient.

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_01HV8Y4QH7C8H1K5K0C8A2B9E4",
  "recipient": {
    "type": "channel",
    "externalId": "+48123456789",
    "channel": "whatsapp"
  },
  "content": {
    "type": "text",
    "text": {
      "body": "Hi Anna, your order is ready for pickup."
    }
  }
}'

Response

202application/json
{
  "message": {
    "id": "msg_01HV8Z2G8Z3H5M9K2S6A1N0P4",
    "createdAt": "2026-04-30T10:36:00Z",
    "updatedAt": "2026-04-30T10:36:00Z",
    "tenantId": "tn_01HV8Y1N3QPY9X2HBQ1M9E8D0",
    "conversationId": "cnv_01HV8Y7YF5J4Y7M9M7T3H3X2A1",
    "senderType": "user",
    "senderId": "usr_01HV8Y3K2R6G7K3F5B9N8M1Q0",
    "content": {
      "type": "template",
      "template": {
        "name": "order_ready",
        "language": "en"
      }
    },
    "deliveryStatus": "pending"
  },
  "conversation": {
    "id": "cnv_01HV8Y7YF5J4Y7M9M7T3H3X2A1",
    "channel": "whatsapp",
    "externalId": "48123456789",
    "inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
    "name": "Anna Kowalska",
    "contactId": "con_01HV8Y5R5RFMS0TFK6PKF9H2S8",
    "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

Related schemas

Request

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

Response

200application/json
{
  "message": {
    "id": "msg_01HV8Z2G8Z3H5M9K2S6A1N0P4",
    "createdAt": "2026-04-30T10:36:00Z",
    "updatedAt": "2026-04-30T10:36:02Z",
    "tenantId": "tn_01HV8Y1N3QPY9X2HBQ1M9E8D0",
    "conversationId": "cnv_01HV8Y7YF5J4Y7M9M7T3H3X2A1",
    "senderType": "user",
    "senderId": "usr_01HV8Y3K2R6G7K3F5B9N8M1Q0",
    "content": {
      "type": "text",
      "text": {
        "body": "Hi Anna, your order is ready for pickup."
      }
    },
    "deliveryStatus": "delivered",
    "channelMessageId": "wamid.HBgLMjQxMjM0NTY3ODkVAgARGBI"
  },
  "conversation": {
    "id": "cnv_01HV8Y7YF5J4Y7M9M7T3H3X2A1",
    "channel": "whatsapp",
    "externalId": "48123456789",
    "inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
    "name": "Anna Kowalska",
    "contactId": "con_01HV8Y5R5RFMS0TFK6PKF9H2S8",
    "contactName": "Anna Kowalska",
    "lastMessageAt": "2026-04-30T10:35:00Z",
    "lastMessagePreview": "Thanks, I will check it now.",
    "lastMessageSender": "customer"
  }
}
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. Use the same Idempotency-Key when retrying the same upload request.

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_01HV8Z6K9D2R4S7T8P5N3Q1M0",
  "mediaType": "document",
  "mimeType": "application/pdf",
  "filename": "invoice-4827.pdf",
  "fileSize": 184201,
  "url": "/media/tn_01HV8Z6K9D2R4S7T8P5N3Q1M0/uploads/mda_01HV8Z6K9D2R4S7T8P5N3Q1M0"
}
get/conversations

List conversations#

Returns conversations visible 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
    pageSize
    Type
    query integer
    Description
    Optional parameter.
  • Name
    pageToken
    Type
    query string
    Description
    Optional parameter.
  • Name
    interacted
    Type
    query boolean
    Description
    Optional parameter.
  • Name
    status
    Type
    query array<enum>
    Description
    Optional parameter.
  • Name
    sort
    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 pageSize="{pageSize}" \
  -d pageToken="{pageToken}" \
  -d interacted="{interacted}" \
  -d status="{status}" \
  -d sort="{sort}"

Response

200application/json
{
  "conversations": [
    {
      "id": "cnv_01HV8Y7YF5J4Y7M9M7T3H3X2A1",
      "channel": "whatsapp",
      "externalId": "48123456789",
      "inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
      "name": "Anna Kowalska",
      "contactId": "con_01HV8Y5R5RFMS0TFK6PKF9H2S8",
      "contactName": "Anna Kowalska",
      "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 the message history for a conversation, newest-page token included when more messages are available.

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
    pageSize
    Type
    query integer
    Description
    Optional parameter.
  • 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

Related schemas

Request

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

Response

200application/json
{
  "messages": [
    {
      "id": "msg_01HV8Z2G8Z3H5M9K2S6A1N0P4",
      "createdAt": "2026-04-30T10:36:00Z",
      "updatedAt": "2026-04-30T10:36:02Z",
      "tenantId": "tn_01HV8Y1N3QPY9X2HBQ1M9E8D0",
      "conversationId": "cnv_01HV8Y7YF5J4Y7M9M7T3H3X2A1",
      "senderType": "user",
      "senderId": "usr_01HV8Y3K2R6G7K3F5B9N8M1Q0",
      "content": {
        "type": "text",
        "text": {
          "body": "Hi Anna, your order is ready for pickup."
        }
      },
      "deliveryStatus": "delivered",
      "channelMessageId": "wamid.HBgLMjQxMjM0NTY3ODkVAgARGBI"
    }
  ],
  "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
    MessageContent
    Description
    Required request attribute.

Optional attributes

  • Name
    inboxId
    Type
    string
    Description
    Sender inbox ID. Required for first-message sends to a channel recipient.

Responses

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

Related schemas

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_01HV8Z2G8Z3H5M9K2S6A1N0P4",
    "createdAt": "2026-04-30T10:36:00Z",
    "updatedAt": "2026-04-30T10:36:00Z",
    "tenantId": "tn_01HV8Y1N3QPY9X2HBQ1M9E8D0",
    "conversationId": "cnv_01HV8Y7YF5J4Y7M9M7T3H3X2A1",
    "senderType": "user",
    "senderId": "usr_01HV8Y3K2R6G7K3F5B9N8M1Q0",
    "content": {
      "type": "template",
      "template": {
        "name": "order_ready",
        "language": "en"
      }
    },
    "deliveryStatus": "pending"
  },
  "conversation": {
    "id": "cnv_01HV8Y7YF5J4Y7M9M7T3H3X2A1",
    "channel": "whatsapp",
    "externalId": "48123456789",
    "inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
    "name": "Anna Kowalska",
    "contactId": "con_01HV8Y5R5RFMS0TFK6PKF9H2S8",
    "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}/read

Mark conversation as read#

Marks messages up to the specified message as read for the authenticated user

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}/read" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "lastMessageId": "string"
}'

Response

200application/json
{
  "id": "cnv_01HV8Y7YF5J4Y7M9M7T3H3X2A1",
  "channel": "whatsapp",
  "externalId": "48123456789",
  "inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
  "name": "Anna Kowalska",
  "contactId": "con_01HV8Y5R5RFMS0TFK6PKF9H2S8",
  "contactName": "Anna Kowalska",
  "lastMessageAt": "2026-04-30T10:35:00Z",
  "lastMessagePreview": "Thanks, I will check it now.",
  "lastMessageSender": "customer"
}
post/conversations/{id}/close

Close conversation#

Closes the active session for the 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.

Responses

  • Name
    200
    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}"

Response

200
200 Conversation closed