Introduction
# ManyChat
Access the ManyChat API with managed authentication. Manage subscribers, tags, custom fields, flows, and send messages through chat automation.
## Quick Start
```bash # Get page info python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/manychat/fb/page/getInfo') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## Base URL
``` https://gateway.maton.ai/manychat/{native-api-path} ```
Replace `{native-api-path}` with the actual ManyChat API endpoint path. The gateway proxies requests to `api.manychat.com` and automatically injects your API token.
## Authentication
All requests require the Maton API key in the Authorization header:
``` Authorization: Bearer $MATON_API_KEY ```
**Environment Variable:** Set your API key as `MATON_API_KEY`:
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### Getting Your API Key
1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key
## Connection Management
Manage your ManyChat connections at `https://ctrl.maton.ai`.
### List Connections
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=manychat&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### Create Connection
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'manychat'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### Get Connection
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**Response:** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "manychat", "metadata": {} } } ```
Complete the connection by providing your ManyChat API key through the connection URL.
### Delete Connection
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### Specifying Connection
If you have multiple ManyChat connections, specify which one to use with the `Maton-Connection` header:
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/manychat/fb/page/getInfo') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
If omitted, the gateway uses the default (oldest) active connection.
## API Reference
### Page Operations
#### Get Page Info
```bash GET /manychat/fb/page/getInfo ```
Rate limit: 100 queries per second
**Response:** ```json { "status": "success", "data": { "id": 123456789, "name": "Page Name", "category": "Business", "avatar_link": "https://...", "username": "pagename", "about": "About text", "description": "Page description", "is_pro": true, "timezone": "America/New_York" } } ```
### Tag Operations
#### List Tags
```bash GET /manychat/fb/page/getTags ```
Rate limit: 100 queries per second
**Response:** ```json { "status": "success", "data": [ {"id": 1, "name": "VIP"}, {"id": 2, "name": "Customer"} ] } ```
#### Create Tag
```bash POST /manychat/fb/page/createTag Content-Type: application/json
{ "name": "New Tag" } ```
Rate limit: 10 queries per second
#### Remove Tag from Page
```bash POST /manychat/fb/page/removeTag Content-Type: application/json
{ "tag_id": 123 } ```
Rate limit: 10 queries per second. Removes tag from page and all subscribers.
#### Remove Tag by Name
```bash POST /manychat/fb/page/removeTagByName Content-Type: application/json
{ "tag_name": "Old Tag" } ```
Rate limit: 10 queries per second
### Custom Field Operations
#### List Custom Fields
```bash GET /manychat/fb/page/getCustomFields ```
Rate limit: 100 queries per second
**Response:** ```json { "status": "success", "data": [ {"id": 1, "name": "phone_number", "type": "text"}, {"id": 2, "name": "purchase_count", "type": "number"} ] } ```
#### Create Custom Field
```bash POST /manychat/fb/page/createCustomField Content-Type: application/json
{ "caption": "Phone Number", "type": "text", "description": "Customer phone number" } ```
Rate limit: 10 queries per second
**Field Types:** `text`, `number`, `date`, `datetime`, `boolean`
### Bot Field Operations
#### List Bot Fields
```bash GET /manychat/fb/page/getBotFields ```
Rate limit: 100 queries per second
#### Create Bot Field
```bash POST /manychat/fb/page/createBotField Content-Type: application/json
{ "name": "counter", "type": "number", "description": "Global counter", "value": 0 } ```
Rate limit: 10 queries per second
#### Set Bot Field
```bash POST /manychat/fb/page/setBotField Content-Type: application/json
{ "field_id": 123, "field_value": 42 } ```
Rate limit: 10 queries per second
#### Set Bot Field by Name
```bash POST /manychat/fb/page/setBotFieldByName Content-Type: application/json
{ "field_name": "counter", "field_value": 42 } ```
Rate limit: 10 queries per second
#### Set Multiple Bot Fields
```bash POST /manychat/fb/page/setBotFields Content-Type: application/json
{ "fields": [ {"field_id": 123, "field_value": "value1"}, {"field_name": "field2", "field_value": "value2"} ] } ```
Rate limit: 10 queries per second. Maximum 20 fields per request.
### Flow Operations
#### List Flows
```bash GET /manychat/fb/page/getFlows ```
Rate limit: 10 queries per second
**Response:** ```json { "status": "success", "data": { "flows": [ {"ns": "content123456", "name": "Welcome Flow", "folder_id": 1} ], "folders": [ {"id": 1, "name": "Main Folder"} ] } } ```
### Growth Tools
#### List Growth Tools
```bash GET /manychat/fb/page/getGrowthTools ```
Rate limit: 100 queries per second
### OTN Topics
#### List OTN Topics
```bash GET /manychat/fb/page/getOtnTopics ```
Rate limit: 100 queries per second
### Subscriber Operations
#### Get Subscriber Info
```bash GET /manychat/fb/subscriber/getInfo?subscriber_id=123456789 ```
Rate limit: 10 queries per second
**Response:** ```json { "status": "success", "data": { "id": 123456789, "name": "John Doe", "first_name": "John", "last_name": "Doe", "gender": "male", "profile_pic": "https://...", "subscribed": "2025-01-15T10:30:00Z", "last_interaction": "2025-02-01T14:20:00Z", "tags": [{"id": 1, "name": "VIP"}], "custom_fields": [{"id": 1, "name": "phone", "value": "+1234567890"}] } } ```
#### Find Subscriber by Name
```bash GET /manychat/fb/subscriber/findByName?name=John%20Doe ```
Rate limit: 10 queries per second. Maximum 100 results.
#### Find Subscriber by Custom Field
```bash GET /manychat/fb/subscriber/findByCustomField?field_id=123&field_value=value ```
Rate limit: 10 queries per second. Works with Text and Number fields. Maximum 100 results.
#### Find Subscriber by System Field
```bash GET /manychat/fb/subscriber/[email protected] ```
```bash GET /manychat/fb/subscriber/findBySystemField?phone=+1234567890 ```
Rate limit: 50 queries per second. Set either `email` OR `phone` parameter.
#### Get Subscriber by User Ref
```bash GET /manychat/fb/subscriber/getInfoByUserRef?user_ref=123456 ```
#### Create Subscriber
```bash POST /manychat/fb/subscriber/createSubscriber Content-Type: application/json
{ "first_name": "John", "last_name": "Doe", "phone": "+1234567890", "email": "[email protected]", "gender": "male", "has_opt_in_sms": true, "has_opt_in_email": true, "consent_phrase": "I agree to receive messages" } ```
Rate limit: 10 queries per second
**Note:** Importing subscribers with phone or email requires special permissions from ManyChat. Contact ManyChat support to enable this feature for your account.
#### Update Subscriber
```bash POST /manychat/fb/subscriber/updateSubscriber Content-Type: application/json
{ "subscriber_id": 123456789, "first_name": "John", "last_name": "Smith", "phone": "+1234567890", "email": "[email protected]" } ```
Rate limit: 10 queries per second
#### Add Tag to Subscriber
```bash POST /manychat/fb/subscriber/addTag Content-Type: application/json
{ "subscriber_id": 123456789, "tag_id": 1 } ```
Rate limit: 10 queries per second
#### Add Tag by Name
```bash POST /manychat/fb/subscriber/addTagByName Content-Type: application/json
{ "subscriber_id": 123456789, "tag_name": "VIP" } ```
Rate limit: 10 queries per second
#### Remove Tag from Subscriber
```bash POST /manychat/fb/subscriber/removeTag Content-Type: application/json
{ "subscriber_id": 123456789, "tag_id": 1 } ```
Rate limit: 10 queries per second
#### Remove Tag by Name
```bash POST /manychat/fb/subscriber/removeTagByName Content-Type: application/json
{ "subscriber_id": 123456789, "tag_name": "VIP" } ```
Rate limit: 10 queries per second
#### Set Custom Field
```bash POST /manychat/fb/subscriber/setCustomField Content-Type: application/json
{ "subscriber_id": 123456789, "field_id": 1, "field_value": "+1234567890" } ```
Rate limit: 10 queries per second
#### Set Custom Field by Name
```bash POST /manychat/fb/subscriber/setCustomFieldByName Content-Type: application/json
{ "subscriber_id": 123456789, "field_name": "phone_number", "field_value": "+1234567890" } ```
Rate limit: 10 queries per second
#### Set Multiple Custom Fields
```bash POST /manychat/fb/subscriber/setCustomFields Content-Type: application/json
{ "subscriber_id": 123456789, "fields": [ {"field_id": 1, "field_value": "value1"}, {"field_name": "field2", "field_value": "value2"} ] } ```
Rate limit: 10 queries per second. Maximum 20 fields per request.
#### Verify Subscriber by Signed Request
```bash POST /manychat/fb/subscriber/verifyBySignedRequest Content-Type: application/json
{ "subscriber_id": 123456789, "signed_request": "signed_request_token" } ```
Rate limit: 10 queries per second
### Sending Operations
#### Send Content
```bash POST /manychat/fb/sending/sendContent Content-Type: application/json
{ "subscriber_id": 123456789, "data": { "version": "v2", "content": { "messages": [ { "type": "text", "text": "Hello! How can I help you today?" } ] } }, "message_tag": "CONFIRMED_EVENT_UPDATE" } ```
Rate limit: 25 queries per second
**Message Tags:** Required for sending outside the 24-hour messaging window - `CONFIRMED_EVENT_UPDATE` - `POST_PURCHASE_UPDATE` - `ACCOUNT_UPDATE`
**OTN (One-Time Notification):** ```json { "subscriber_id": 123456789, "data": {...}, "otn_topic_name": "Price Drop Alert" } ```
#### Send Content by User Ref
```bash POST /manychat/fb/sending/sendContentByUserRef Content-Type: application/json
{ "user_ref": 123456, "data": { "version": "v2", "content": { "messages": [ { "type": "text", "text": "Welcome!" } ] } } } ```
Rate limit: 25 queries per second
#### Send Flow
```bash POST /manychat/fb/sending/sendFlow Content-Type: application/json
{ "subscriber_id": 123456789, "flow_ns": "content123456" } ```
Rate limit: 20 queries per second, maximum 100 per subscriber per hour
## Message Content Format
ManyChat uses a structured content format for sending messages:
### Text Message
```json { "version": "v2", "content": { "messages": [ { "type": "text", "text": "Your message here" } ] } } ```
### Image Message
```json { "version": "v2", "content": { "messages": [ { "type": "image", "url": "https://example.com/image.jpg" } ] } } ```
### Quick Replies
```json { "version": "v2", "content": { "messages": [ { "type": "text", "text": "Choose an option:", "quick_replies": [ {"type": "node", "caption": "Option 1", "target": "content123"}, {"type": "node", "caption": "Option 2", "target": "content456"} ] } ] } } ```
### Buttons
```json { "version": "v2", "content": { "messages": [ { "type": "text", "text": "Click a button:", "buttons": [ {"type": "url", "caption": "Visit Website", "url": "https://example.com"}, {"type": "flow", "caption": "Start Flow", "target": "content123"} ] } ] } } ```
## Code Examples
### JavaScript
```javascript // Get page info const response = await fetch( 'https://gateway.maton.ai/manychat/fb/page/getInfo', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json();
// Send a message const sendResponse = await fetch( 'https://gateway.maton.ai/manychat/fb/sending/sendContent', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ subscriber_id: 123456789, data: { version: 'v2', content: { messages: [{ type: 'text', text: 'Hello!' }] } } }) } ); ```
### Python
```python import os import requests
# Get page info response = requests.get( 'https://gateway.maton.ai/manychat/fb/page/getInfo', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'} ) data = response.json()
# Send a message send_response = requests.post( 'https://gateway.maton.ai/manychat/fb/sending/sendContent', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, json={ 'subscriber_id': 123456789, 'data': { 'version': 'v2', 'content': { 'messages': [{'type': 'text', 'text': 'Hello!'}] } } } ) ```
## Notes
- Subscriber IDs are unique within your ManyChat page - Flow namespaces (flow_ns) are used to identify specific automation flows - The `message_tag` parameter is required when sending messages outside the 24-hour messaging window - OTN (One-Time Notification) allows sending one message per topic subscription - Most POST endpoints return `{"status": "success"}` on success - IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets to disable glob parsing - IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments
## Error Handling
| Status | Meaning | |--------|---------| | 400 | Missing ManyChat connection | | 401 | Invalid or missing Maton API key | | 429 | Rate limited | | 4xx/5xx | Passthrough error from ManyChat API |
### ManyChat Error Codes
| Code | Meaning | |------|---------| | 2011 | Subscriber not found | | 2012 | User ref not found | | 3011 | Invalid message content | | 3021 | Message tag required | | 3031 | OTN topic not found |
### Troubleshooting: API Key Issues
1. Check that the `MATON_API_KEY` environment variable is set:
```bash echo $MATON_API_KEY ```
2. Verify the API key is valid by listing connections:
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### Troubleshooting: Invalid App Name
1. Ensure your URL path starts with `manychat`. For example:
- Correct: `https://gateway.maton.ai/manychat/fb/page/getInfo` - Incorrect: `https://gateway.maton.ai/fb/page/getInfo`
## Resources
- [ManyChat API Documentation](https://api.manychat.com/swagger) - [ManyChat API Key Generation Guide](https://help.manychat.com/hc/en-us/articles/14959510331420) - [ManyChat Dev Program](https://help.manychat.com/hc/en-us/articles/14281269835548) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:[email protected])