# AIFLOW

> Multi-channel messaging automation platform for Israeli businesses.
> Connect WhatsApp (official + personal/unofficial), Facebook Messenger,
> Instagram DM, Telegram, Gmail and Outlook — receive inbound messages,
> trigger outbound flows, build no-code chatbot flows, and reply across
> all channels from a single REST API.

AIFLOW is used by CRM systems, external automations, and AI agents to
send messages, read conversation transcripts, and reply to customers —
without needing to know which channel the customer used. The platform
handles routing, token management, and channel-specific rules (e.g.
WhatsApp 24h window, Messenger 7-day HUMAN_AGENT window) automatically.

## Docs

- [Integration hub (start here)](https://flow.txi.co.il/docs/integrations): Persona-based guide for AI agents, developers, and non-technical users
- [External API full reference](https://flow.txi.co.il/docs/external-send-api): Complete endpoint reference — channels, auth, code samples, error codes
- [OpenAPI 3.1 spec](https://flow.txi.co.il/api/openapi.json): Machine-readable JSON spec for all external endpoints (use this to generate clients)
- [Developer docs (flows, webhooks, outbound)](https://flow.txi.co.il/docs): Webhook triggers, flow-based outbound, lead ingestion, authentication

## Authentication

All external endpoints use `Authorization: Bearer <api_key>`.
API key is per-tenant, found at /settings/webhooks.
60 requests/minute per tenant across all endpoints.

## Supported Channels

| Channel | Receive | Send text | Send media | Template | Window |
|---|---|---|---|---|---|
| whatsapp_unofficial (Green API) | ✓ | ✓ | ✓ | AIFLOW personal | none |
| whatsapp (Meta Cloud) | ✓ | ✓ | planned | Meta-approved | 24h free / none for template |
| messenger | ✓ | ✓ | ✓ | — | 24h RESPONSE / 7d HUMAN_AGENT |
| instagram | ✓ | ✓ | ✓ | — | 24h |
| telegram | ✓ | ✓ | ✓ | — | none |
| email (Gmail/Outlook) | ✓ | ✓ (reply-to-thread) | planned | — | none |

## Key Endpoints

### POST /api/external/send
Proactive outbound message to any supported channel.
Every response includes `requestId` (UUID) for async correlation.
After each attempt, a `message.sent` or `message.failed` webhook fires to the tenant's subscribers.

Channel routing via `channel` field:
- `whatsapp_green` — Requires `instanceId` (DB UUID). All types (text/image/video/document/template).
- `whatsapp_official` — Template only. Pass `templateName` + optional `phoneNumberId`.
- `messenger` — Pass `psid` or `to` (Messenger PSID). HUMAN_AGENT tag applied automatically.
- `instagram` — Pass `igsid` or `to` (Instagram-scoped ID).
- `telegram` — Pass `chatId` or `to`. Optional `configId` for multiple bots.
- `email` — Pass `to` (email addr) + `configId` (EmailConfig.id). Required.

Backward compat: omit `channel` + pass `instanceId` → whatsapp_green.

Returns: `{ ok, requestId, status, messageId?, channel, error? }`
Status values: `sent` | `failed` | `invalid_params` | `config_error` | `provider_error`
HTTP: 401/429 pre-auth (no requestId). All post-auth → HTTP 200 always.

### GET /api/external/conversations
List conversations with optional filters: `channel`, `status`, `limit` (max 200), `offset`.
Returns: `{ ok, conversations: [...], pagination: { limit, offset, hasMore } }`

### GET /api/external/conversations/{id}
Single conversation with transcript. Query: `limit` (max 500).
Returns: `{ ok, conversation, messages: [...], pagination }`
Each message: `{ id, action, direction, channel, type, text, mediaUrl, deliveryStatus, spam, timestamp }`

### POST /api/external/conversations/{id}/reply
Reply to an existing conversation — channel-aware routing. No instanceId needed.
Supports: `text`, `image`, `video`, `document`, `template` (Meta-approved, Cloud only).
Returns: `{ ok, messageId, channel, type }`
Error 409 when outside send window (use type=template for Cloud).

### POST /api/webhook/outbound
Trigger a pre-built flow for a phone number (initiates or resumes conversation).
Auth: JWT or API access token (see /docs for setup).
Body: `{ clientId, flowId?, phone, name?, ... }`

## Webhook Events (incoming to your server)

AIFLOW POSTs to your configured webhook URL on every conversation and send event.
Every event contains a top-level `platform` block with channel details and
a `replyEndpoint` ready to use — no need to track which channel was used.

### Conversation events
- `conversation.message_received` — inbound customer message
- `conversation.message_sent` — outbound bot/agent message
- `conversation.flow_completed` — conversation flow ended (outcome may be 'abandoned')
- `conversation.abandoned` — customer never replied; idle timeout triggered

### Send API events (async delivery confirmation)
Fired after every POST /api/external/send attempt, success or failure.
Correlate with the `requestId` from the API response.

- `message.sent` — message delivered to provider
  ```json
  { "event": "message.sent", "data": { "requestId": "...", "channel": "whatsapp_unofficial:...", "to": "972...", "type": "text", "messageId": "BAE5...", "sentAt": "..." } }
  ```
- `message.failed` — send attempt failed
  ```json
  { "event": "message.failed", "data": { "requestId": "...", "channel": "...", "reason": "provider_error", "error": "..." } }
  ```

The `platform` block (on all events) includes:
- `type`: whatsapp_green | whatsapp_official | messenger | instagram | email | telegram
- `replyEndpoint.url`: ready-to-use POST URL for replying
- `replyEndpoint.auth`: `Authorization: Bearer <api_key>`
- Channel-specific IDs: `idInstance`, `phoneNumberId`, `pageId`, `igAccountId`, etc.

## Error Codes

- 401 Invalid/missing API key (no requestId in body)
- 429 Rate limit (60 req/min per tenant — requestId included)
- 200 + ok:false All post-auth errors — check `status` and `error` fields

## Integration Patterns for AI Agents

### Pattern 1: Receive webhook → reply immediately
1. Your server receives POST from AIFLOW with event `conversation.message_received`
2. Read `platform.replyEndpoint.url` from the payload
3. POST to that URL with `Authorization: Bearer <api_key>` and `{ type, text }`
4. No need to know channel, instance, or PSID — AIFLOW handles routing

### Pattern 2: Proactive outreach with async confirmation
1. POST /api/external/send with `channel`, `to`, `type`, `text` (or channel-specific params)
2. Save the `requestId` from the response
3. Your webhook receives `message.sent` or `message.failed` with the same `requestId`
4. For existing conversations: POST /api/external/conversations/{id}/reply instead

### Pattern 3: CRM sync — read transcript
1. GET /api/external/conversations?channel=whatsapp_unofficial&limit=100
2. For each conversation: GET /api/external/conversations/{id}?limit=200
3. Each message has `direction` (inbound/outbound), `type`, `text`, `timestamp`

## Phone Number Format

All phone numbers stored in E.164 without leading +.
Israel: `972501234567` (not `0501234567` or `+972501234567`).
The /api/external/send endpoint normalises Israeli local format automatically.

## Base URL

https://flow.txi.co.il