Conversations and contacts

// 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 https://api.flow.engineer/v0/conversations/conv_01JB8ZC3K5M7P9R1T3V5X7Z9B1/basic \
  -H "Authorization: Bearer $FLOW_MESSAGING_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Your order has shipped."}'

​

The objects

​

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",
  "type": "direct",
  "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; 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.
• type: direct (one contact, in contact) or group. Read a missing type as direct.
• group (group conversations only): the group chat’s name, when it has one, and its participants, each a contact. A group has no contact; each inbound message’s from says who wrote. Group chats reach your app only from dedicated iMessage lines people add to them, and the API cannot create a group or change who is in it. See iMessage.
• opted_in: the contact wrote first, joined the sandbox, or you recorded their consent. Always true on groups.
• metadata: up to 20 string pairs of your own (for example your user ID), kept with the conversation.

​

Starting a conversation

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

​

Related

• Message kinds: what each channel takes, one endpoint per kind.
• List conversations and list a conversation’s messages.