canonical: https://jentic.com/apis/chatfuel.com/chatfuel

# Chatfuel API

Jentic publishes the only available OpenAPI specification for Chatfuel API, keeping it validated and agent-ready. Chatfuel is a chatbot platform for Facebook Messenger, Instagram, and WhatsApp. The public REST API is small and focused: list bot users, send a message to a single user, set user attributes that flows can branch on, and broadcast a message to the bot's audience. Authentication is by Chatfuel token supplied as a query parameter on the relevant endpoints.

## For AI agents

Send messages to Chatfuel bot users, set user attributes, and broadcast to the bot's audience. Token-authenticated REST API with 4 endpoints scoped per bot.

## Scope

Does not handle flow authoring, NLP intent training, or chatbot building UI - use for runtime messaging, attribute writes, and broadcasts on existing Chatfuel bots only.

## Capabilities

- Send a one-off message to a specific bot user via POST /bots/{botId}/users/{userId}/send
- List the users of a bot via GET /bots/{botId}/users with optional tag and segment filters
- Update user attributes that downstream Chatfuel flows can branch on via PUT /bots/{botId}/users/{userId}/attributes
- Broadcast a message to all users of a bot via POST /bots/{botId}/broadcast
- Filter the bot user list by tag or segment to target re-engagement messages
- Drive flow personalisation by writing per-user attributes from external systems
- Trigger one-to-one conversations from external events without opening the Chatfuel UI

## Use cases

### Send a transactional reply from your backend to a Messenger user

When an external system has news for a known Messenger subscriber - order shipped, appointment confirmed - call POST /bots/{botId}/users/{userId}/send to deliver the message inside the existing chat thread. Chatfuel handles channel-specific delivery so the same call works regardless of whether the user came in via Messenger, Instagram, or WhatsApp.

Example prompt: After an order ships, call POST /bots/{botId}/users/{userId}/send to deliver 'Your order #1234 has shipped' to the user with the matching Chatfuel userId

### Personalise flow branches with external data

Write per-user attributes via PUT /bots/{botId}/users/{userId}/attributes so Chatfuel flows can branch on values that originated outside Chatfuel - CRM lifecycle stage, last-purchase date, plan tier. Because attributes drive flow logic, this is the right way to keep flow personalisation in sync with the source-of-truth system.

Example prompt: Set the attribute lifecycle_stage='paying_customer' and plan_tier='pro' on Chatfuel userId 'msgr-9988' under botId 'acme-bot'

### Run a re-engagement broadcast to a tagged segment

Use GET /bots/{botId}/users with the tag query parameter to enumerate dormant subscribers, then POST /bots/{botId}/broadcast to deliver a re-engagement message scoped to the same tag. Chatfuel's tag/segment filters let an agent target the broadcast without exporting the user list.

Example prompt: List Chatfuel users with tag 'dormant_30d' and broadcast a re-engagement message to that segment via POST /bots/{botId}/broadcast

### Drive a Chatfuel bot from an AI agent

An AI agent uses Jentic to discover Chatfuel's send and broadcast endpoints, loads their schemas, and triggers messenger-channel outreach in response to natural-language requests like 'tell my Messenger subscribers we just launched the new feature'. The Chatfuel token sits in Jentic's vault so the agent never sees it.

Example prompt: Search Jentic for 'send a chatfuel broadcast', load the schema, and broadcast 'New feature launched: shareable receipts' to all users of botId 'acme-bot'

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /bots/{botId}/users | List bot users (optional tag/segment filters) |
| POST | /bots/{botId}/users/{userId}/send | Send a message to a specific user |
| PUT | /bots/{botId}/users/{userId}/attributes | Set attributes on a user |
| POST | /bots/{botId}/broadcast | Send a broadcast to the bot's audience |

## Key resources

- **Bot Users** — List the users of a bot, filterable by tag or segment
- **User Send** — Deliver a one-to-one message to a specific user
- **User Attributes** — Write per-user attributes that flows branch on
- **Broadcasts** — Send a message to the bot's full audience

## Why Jentic

- **Setup:** Wiring the Chatfuel API by hand means passing the token in the chatfuel_token query parameter on every messaging call and building the bot and user paths yourself. Through Jentic you install once, import Chatfuel from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Chatfuel puts the bot id in the URL path (/bots/{botId}/...), so a rule can pin your agent to one bot: it can send messages and set user attributes for that bot and nothing else. You choose the operations it may call, so broadcasting to all users is not included unless you add it.
- **Credential handling:** Your Chatfuel token is stored once, encrypted, by your own Jentic One instance and injected into the chatfuel_token parameter at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a chatfuel broadcast' or 'set a chatfuel user attribute', and Jentic returns the matching Chatfuel operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **ChatBot API** — ChatBot.com is a flow-based bot builder - choose it for site-embedded story-driven bots rather than messenger channels.
- **Chatbase API** — Chatbase delivers doc-grounded LLM bots - choose it for free-form Q&A bots rather than messenger flows.
- **ChatKitty API** — ChatKitty provides real-time chat infrastructure - pair it with Chatfuel where in-app chat sits alongside Messenger outreach.

## FAQ

### Why is there no official OpenAPI spec for Chatfuel API?

Chatfuel does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Chatfuel API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Chatfuel API use?

Chatfuel uses an API token passed as the chatfuel_token query parameter on requests against api.chatfuel.com. Through Jentic, the token is stored in your encrypted Jentic One instance and injected into the query string at execution time so it never enters the agent's prompt.

### Can I send a one-off message to a specific Messenger user?

Yes - POST /bots/{botId}/users/{userId}/send delivers a single message to one user. The userId is Chatfuel's identifier for that subscriber, so you must have it from a prior list-users call or a Chatfuel webhook before invoking this endpoint.

### How do I broadcast to a specific segment of users?

List users with GET /bots/{botId}/users using the tag or segment query parameter to confirm the audience, then call POST /bots/{botId}/broadcast with the same segment metadata. Chatfuel applies channel-specific delivery rules so the broadcast respects Messenger/Instagram/WhatsApp policy.

### How do I trigger a Chatfuel broadcast through Jentic?

Run pip install jentic, set JENTIC_AGENT_API_KEY, then search 'send a chatfuel broadcast'. Jentic returns POST /bots/{botId}/broadcast with its request schema. Supply botId and the message body, then execute.

### Are there documented rate limits for the Chatfuel API?

The OpenAPI spec does not declare per-bot rate limits. Messenger and Instagram apply their own platform-level limits to the underlying delivery, so broadcasts and one-off sends can fail downstream even when the Chatfuel API accepts the call. Monitor message-status responses and back off on 429 errors.

### Can I limit what my agent is allowed to do with the Chatfuel API?

Yes. Because you run Jentic One yourself, your own rules decide which Chatfuel operations and credentials the agent may use. Since Chatfuel puts the bot id in the URL path (/bots/{botId}/...), a rule can pin the agent to a single bot and to specific operations, so you can allow it to send one-off messages via POST /bots/{botId}/users/{userId}/send and write attributes via PUT /bots/{botId}/users/{userId}/attributes while withholding broadcasts to the whole audience via POST /bots/{botId}/broadcast. The Chatfuel token is stored by your own instance and injected into the chatfuel_token parameter at execution time, so the agent never sees it and can only act within the scope you grant.