All pages
Channel connectors
With chat_channel (and the required chat.transport scope), your app bridges an external messaging platform (such as a Discord server, a community forum or a regional messenger) into a Resident’s craving inbox. Visitors write on your platform; craving AI and the Resident reply from craving; your connector delivers messages both ways. Every version with chat_channel goes through human review.
Connecting a Resident
After installing your app, the Resident opens it in Your apps, taps Connect an account, and enters the platform account ID your app gives them (plus an optional handle shown on their Home). That creates a channel bound to their installation and account ID, and craving POSTs channel.connected to your webhook. A Resident can connect multiple accounts.
Inbound: Visitors write
POST new Visitor messages (or conversation history) to gc_app_channel_event, signed by your server with your webhook secret:
POST https://api.craving.com/functions/v1/gc_app_channel_event
X-Craving-Signature: t=1757793600,v1=…
{
"client_id": "crv_…",
"platform_account_id": "guild-42",
"event": "message",
"fan": {
"external_id": "user-123",
"display_name": "Alex",
"avatar_url": "https://app.example.com/avatars/alex.jpg"
},
"messages": [
{
"external_message_id": "m-1",
"text": "hi!",
"sent_at": "2026-09-13T20:00:00Z",
"from": "fan",
"attachments": [{ "url": "https://app.example.com/photo.jpg", "mime_type": "image/jpeg" }]
}
]
}fan.external_idis your platform’s identifier for the Visitor. craving namespaces it as<app_id>:<external_id>so IDs never collide across apps.- On the first live message from a Visitor (
newChat), craving POSTs{ "type": "channel.history", "installation_id": "…", "channel_id": "…", "platform_account_id": "…", "fan_external_id": "…", "limit": 200 }to yourhistory_url(10-second timeout). Return{ "messages": […] }to backfill prior context before craving AI replies. You can also push history proactively with"event": "history". - Messages with
"from": "creator"(or sent with"event": "history") are imported as conversation context and never trigger an automatic reply. - Up to 200 messages are processed per request, deduplicated by
external_message_id.
Outbound: craving answers
Every reply sent from craving on that channel is POSTed to your channel.send_url:
{
"type": "channel.send",
"installation_id": "…",
"channel_id": "…",
"platform_account_id": "guild-42",
"fan_external_id": "user-123",
"message_id": "…",
"text": "Hey Alex!",
"attachments": [
{ "kind": "paid_link", "checkout_url": "https://craving.com/c/…", "price_cents": 1500 }
],
"reply_to": null,
"special": null,
"sent_at": "2026-09-13T20:01:00Z"
}Respond with 2xx and { "external_message_id": "…" } within 10 seconds. If your server returns 429 with Retry-After, craving reschedules the delivery after that delay.
Paid attachments never travel as raw media files: if channel.capabilities includes "paid_links", priced content is sent as { "kind": "paid_link", "checkout_url": "…", "price_cents": … }; otherwise the message is skipped. Free media attachments are sent as { "kind": "media", "url": "…" } when channel.capabilities includes "images" or "audio".
Rules
- Only bridge accounts the Resident connected themselves. Keep Visitor
external_idvalues stable over time. - Inbound traffic is rate limited to 600 messages per minute and 100 new Visitors per hour per installation (Rate limits).
- Store only the Visitor data required to route messages, and delete installation data within 30 days of an uninstall.