Conversations, contacts and channels

A conversation is one sender talking with one contact; your agent always replies into a conversation, so the channel is already decided.

TypeScript

// From an event: the conversation is attached and ready to use.
await event.conversation.reply("Thanks! Your order is on its way.");

// From an ID you stored earlier:
await flow.conversation("conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1").send("Your order has shipped.");

curl

curl https://api.flow.engineer/v1/conversations/conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1/messages \
  -H "Authorization: Bearer $FLOW_MESSAGING_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": {"type": "text", "text": "Your order has shipped."}}'

The objects

Object	ID	What it is
Sender	`snd_`	What your agent talks from: a Telegram bot or an iMessage line (a WhatsApp number once WhatsApp is available). See Senders.
Contact	`ct_`	A person on one channel: a phone number, a WhatsApp username, a Telegram user or an iMessage handle.
Conversation	`conv_`	One sender with one contact. Holds the window state and whether the contact opted in.
Message	`msg_`	One message in or out, with typed content and a status.
Event	`evt_`	One entry in your app’s ordered log. See Events and webhooks.

IDs are a prefix plus a ULID, so they sort by creation time.

One channel per conversation

There is no cross-channel identity. The same person on Telegram and on WhatsApp is two contacts and two conversations. Flow never guesses that they are the same person, and never moves a conversation to another channel.
Never assume a phone number. A Telegram contact has a user ID, a WhatsApp contact may have only a username, and an iMessage handle may be an email address. Read contact.address for what the channel gives.
Reply where they wrote. Each event carries conversation.channel, so one agent can serve every channel with the same code.

What a conversation tells you

{
  "id": "conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
  "channel": "telegram",
  "sender": "snd_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
  "contact": "ct_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
  "livemode": true,
  "last_inbound_at": "2026-11-03T10:15:00Z",
  "opted_in": true,
  "created_at": "2026-11-01T08:00:00Z"
}

window_open_until (WhatsApp only, once available; absent on Telegram and iMessage): until when free-form messages may be sent. After it, only a template. Every event repeats it in conversation.window_open_until.
opted_in: the contact wrote first, joined the sandbox, or you recorded their consent.
metadata: up to 20 string pairs of your own (for example your user ID), kept with the conversation.

Starting a conversation

Most conversations start when the person writes first. To write first, use POST /v1/messages with a sender and an address on that sender’s channel. On Telegram that works only for people who already started your bot; Flow’s iMessage lines are reply-only, so they cannot write first.

curl

curl https://api.flow.engineer/v1/messages \
  -H "Authorization: Bearer $FLOW_MESSAGING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "snd_01JB8ZC3K5M7P9R1T3V5X7Z9B1",
    "to": { "telegram_user_id": "123456789" },
    "content": { "type": "text", "text": "Your order has shipped." }
  }'

to takes exactly one of contact, phone, telegram_user_id or handle. Starting a conversation spends the sender’s new-contact budget, and each channel has its own rule for who may be messaged first. See The send gate.

Capabilities: what the conversation’s channel can show right now.
List conversations and list a conversation’s messages.

Get started

Concepts

Channel guides

Agent frameworks

Compare

Conversations, contacts and channels

The objects

One channel per conversation

What a conversation tells you

Starting a conversation

​The objects

​One channel per conversation

​What a conversation tells you

​Starting a conversation

​Related

The objects

One channel per conversation

What a conversation tells you

Starting a conversation

Related