> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api.logicdialog.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api.logicdialog.ai/_mcp/server.

# API messaging

Configure a client under [Project → Channels → API](https://app.logicdialog.ai/channels?tab=api) in a workstream, then [apply the workstream to Live](/api-reference/workstreams-and-publishing/post-api-workspaces-workspace-id-draft-changes-change-id-apply). Each client has an identifier, bearer token, allowed channels, public HTTPS reply webhook and signing secret. Copy the generated credentials before saving. API messaging currently supports Live only.

Channel names describe the customer interaction; replies are delivered to your configured webhook. Sending `channel: "email"` does not cause LogicDialog to send email: your application delivers the reply to the customer.

## Send a customer message

Use [Send a message](/api-reference/messaging-and-history/post-channels-messages).

```sh
curl 'https://app.logicdialog.ai/channels/messages?channel=api&workspaceId=WORKSPACE&environment=live&integrationId=CLIENT' \
  -H "Authorization: Bearer $LOGICDIALOG_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"id":"message-123","channel":"email","customerId":"customer-42","text":"Where is the counter?","subject":"Booking question"}'
```

Returns HTTP 202: `{"accepted":true,"conversationId":"conv_..."}`. Retain that ID and include `conversationId` in subsequent messages to continue the conversation, even after long delays. Without it a new conversation starts. `id` is a stable unique message ID supplied by the client; retry network failures with the identical ID and payload. Reusing the ID for different input returns 409. Messages are processed sequentially within a conversation; 409 means a previous message or delivery is pending. Retry later with the same ID. No cookie or LogicDialog UI session is needed.

Only configured channels are accepted. Customer text is limited to 32,000 characters; the optional subject is limited to 500. The caller cannot override the reply webhook, environment credentials, AI prompt, review policy or delivery adapter. Conversation IDs are scoped to the workspace, environment, API client, channel and customer.

## Receive a reply

The configured webhook receives a [`message.created` event](/api-reference/reply-webhooks/message-created):

```json
{
  "type": "message.created",
  "id": "stable-reply-id",
  "conversationId": "conv_...",
  "channel": "email",
  "customerId": "customer-42",
  "message": {"id":"stable-reply-id","text":"Your approved reply","author":"human"}
}
```

`author` is `assistant` or `human`. Drafts and internal archive acknowledgements are never delivered. A human uses [Live Chat](https://app.logicdialog.ai/live-chat) to edit and send a held reply. The customer application performs final channel delivery.

Verify `LogicDialog-Signature: t=UNIX_SECONDS,v1=HEX_HMAC_SHA256` against the **exact raw body**: HMAC-SHA256 of `timestamp + "." + rawBody`, keyed with the configured signing secret. Reject stale timestamps (five minutes is suitable) and compare signatures in constant time. Accept the message durably and return 2xx promptly. Deduplicate using `id`/`Idempotency-Key`: failures and timeouts retry the same ID roughly every worker cycle (30 seconds). Delivery is at least once, not exactly once. URLs must resolve to public addresses, redirects are not followed, and calls time out after 15 seconds.

Once your server acknowledges delivery, a later conversation-history failure does not cause the webhook to be resent. Acknowledgement does not mean the customer has read the message.

## Fetch history

Use [Get conversation history](/api-reference/messaging-and-history/get-channels-conversations-conversation-id).

```sh
curl 'https://app.logicdialog.ai/channels/conversations/conv_...?workspaceId=WORKSPACE&environment=live&integrationId=CLIENT' \
  -H "Authorization: Bearer $LOGICDIALOG_API_TOKEN"
```

Returns conversation ID, channel, customer ID, state, available summary and public messages. Drafts, ownership credentials, internal commands and delivery settings are excluded. History is read from the conversation archive and may lag while a delivered reply is being archived. API credentials can only retrieve conversations created through that API client, not arbitrary workspace history.

## Test the complete flow

Use a test workspace/client and a callback endpoint you control. Send a message, verify and deduplicate the signed webhook, fetch history, then send another message using the returned conversation ID. If replies are held for review, send the approved reply from [Live Chat](https://app.logicdialog.ai/live-chat).

See [Authentication](/integration-guides/authentication) for credentials and [Reply webhooks and events](/integration-guides/reply-webhooks-and-events) for delivery behaviour and available events.