canonical: https://jentic.com/apis/botcake.io/botcake

# Botcake API

Jentic publishes the only available OpenAPI specification for Botcake API, keeping it validated and agent-ready. Botcake is a chatbot and customer engagement platform that lets brands run automated and live conversations with customers across messaging channels. The API exposes customers, bots, conversations, messages, and analytics so teams can sync customer profiles, deploy and update bots, send and receive messages, and report on conversation volumes. Authentication uses an X-API-Key header.

## For AI agents

Manage Botcake chatbot conversations, customer profiles, bots, and conversation analytics across 18 endpoints.

## Scope

Does not handle SMS, email delivery, or voice calls - use for Botcake chatbot conversation, customer profile, and analytics management only.

## Capabilities

- Create and update customer profiles with attributes used by chatbot flows
- Deploy, update, and remove chatbots tied to a workspace
- Send and read messages within an active conversation
- Open new conversations and update conversation status or assignment
- Pull conversation and message volume analytics for a date range
- Look up a specific conversation by id including its message history
- Delete a customer record to honour data removal requests

## Use cases

### Customer profile sync into Botcake

Marketing and product teams keep Botcake customer profiles in sync with their main customer database so chatbot flows can personalise greetings and segment messages. The API accepts POST /customers for new records and PUT `/customers/{customerId}` for updates, with attributes that bots consume at runtime. Most teams build the sync as a webhook or nightly job in a couple of days.

Example prompt: Create a Botcake customer with email user@example.com, name 'Alex Kim', and attribute plan='pro', then return the new customer id

### Outbound chatbot messaging

Support and lifecycle teams trigger outbound messages from Botcake when an external event happens (order shipped, ticket resolved, renewal upcoming). POST /conversations creates or fetches the active conversation, then POST `/conversations/{conversationId}/messages` sends the message body. Teams typically wire this into existing webhook pipelines within a sprint.

Example prompt: Open a conversation with customer cust_123 and send the message 'Your order has shipped, tracking number XYZ123'

### Conversation analytics dashboards

Operations leaders want a daily view of conversation volume, response load, and busy windows. GET `/analytics/conversations` and GET `/analytics/messages` return time-series counts that feed BI tools or weekly reports. Dashboards usually go live in a day once authentication and date filtering are in place.

Example prompt: Pull GET `/analytics/conversations` for the last 7 days grouped by day and report the busiest day with its count

### Agent-driven Botcake operations via Jentic

An AI agent monitors a queue of customer events and uses Botcake to message the right customer, update their profile, or resolve their conversation. Through Jentic the agent searches for 'send a Botcake message' or 'update a Botcake customer', loads the schema, and executes the call while the X-API-Key stays inside your Jentic One instance.

Example prompt: Search Jentic for 'send a Botcake message', load the schema, and execute it for conversation conv_777 with the message 'Thanks for your patience, your refund is processed.'

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/customers` | Create a customer profile |
| PUT | `/customers/{customerId}` | Update a customer profile |
| POST | `/conversations` | Open a new conversation |
| POST | `/conversations/{conversationId}/messages` | Send a message in a conversation |
| GET | `/conversations/{conversationId}/messages` | List messages in a conversation |
| POST | `/bots` | Create a bot |
| GET | `/analytics/conversations` | Conversation volume analytics |
| GET | `/analytics/messages` | Message volume analytics |

## Key resources

- **Customers** — Create, update, retrieve, and delete customer profiles with attributes
- **Conversations** — Open, list, and update conversations between bots and customers
- **Messages** — List and post messages within a specific conversation
- **Bots** — Manage chatbots configured in the workspace
- **Analytics** — Conversation and message volume metrics over time

## Why Jentic

- **Setup:** Wiring Botcake by hand means setting the X-API-Key header, learning its conversation and customer models, and stitching the chatbot message and analytics calls together yourself. Through Jentic you install once, import the Botcake API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Botcake puts the resource id in the URL path (`/customers/{customerId}`, `/conversations/{conversationId}/messages`), so a rule can pin your agent to one conversation or customer. You choose the operations it may call, so writes like updating a customer or creating a bot are only available if you add them, and an analytics agent can stay on the read paths.
- **Credential handling:** Your Botcake X-API-Key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a chatbot message' or 'update a Botcake customer', and Jentic returns the matching Botcake operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Chatfuel API** — No-code chatbot platform with a similar focus on Messenger and customer engagement.
- **Tidio API** — Live chat and chatbot platform popular with e-commerce stores.
- **Intercom API** — Customer messaging platform with deeper support and product-tour features.
- **ChatBot API** — Bot-building platform that pairs with Botcake to author flows used in Botcake conversations.

## FAQ

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

Botcake does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Botcake 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 Botcake API use?

Botcake uses an API key passed in the X-API-Key request header. Issue the key from your Botcake workspace and store it in your Jentic One instance so the raw key is never exposed to agents at execution time.

### Can I send a chatbot message with the Botcake API?

Yes. POST /conversations to open or fetch an active conversation, then POST `/conversations/{conversationId}/messages` with the message body. The endpoint returns the created message id, which you can correlate with later analytics calls.

### How do I update a customer's attributes through Jentic?

Run pip install jentic, then search Jentic for 'update a Botcake customer', load the PUT `/customers/{customerId}` schema, and execute it with the customer id and the attribute payload. Jentic injects the X-API-Key automatically.

### What are the rate limits for the Botcake API?

Botcake does not document explicit per-second rate limits in the spec. For bulk customer syncs, batch updates and stagger requests; for analytics, query daily aggregates rather than minute-level windows to avoid unnecessary calls.

### Can I pull conversation volume analytics?

Yes. GET `/analytics/conversations` and GET `/analytics/messages` return counts over a time range, suitable for daily and weekly reports. Pair them with conversation id lookups when you need to drill from a count down to specific transcripts.

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

Yes. Because you run Jentic One yourself, your own rules decide which Botcake operations and which credential the agent may use. Botcake puts the resource id in the URL path, so `/customers/{customerId}` and `/conversations/{conversationId}/messages` let you pin an agent to a single customer or conversation. You choose the operations it can call, so writes like updating a customer or creating a bot are available only if you add them, and a reporting agent can stay on the read-only `/analytics/conversations` and `/analytics/messages` paths.