Developers
An AI agent API to connect Gental to your systems
Have an app, a CRM or an internal tool where the agent should answer? Gental’s API channel lets your systems start a conversation, send a customer’s message and get the answer with its sources, while every conversation shows in your team inbox like any other channel.
Updated
What you can do with the Gental agent API
Scoped API keys
Each key has the scopes you pick and can be limited to some agents. It is shown once, and revoking it stops it at once.
REST and streaming
Get the full answer as JSON with sources, or stream it with server-sent events and show it as it is written.
Files and images
Upload a customer’s photo or document into the conversation, and the agent reads it and answers.
Signed webhooks
New messages, replies, handoffs, leads and linked number status. Every request is signed with HMAC-SHA256 and retried on failure.
Handover to your team
When a teammate holds the conversation the API tells you, and the teammate’s reply reaches you as a webhook.
Linked numbers from your system
Send messages from a linked WhatsApp number, manage its contacts, and decide who answers a chat: the agent or a person.
How to connect the agent to your system, step by step
The flow in short, without the error and limit details.
Create an API key
In Settings, Developers, pick the agents.chat scope, then copy the key and keep it on your server (never in a browser or mobile app).
Publish the agent to the API
Turn on API publishing on the agent. Only the published version answers; drafts stay in the dashboard.
Start a conversation
Your system sends POST /agents/{agentId}/conversations and gets a conversation id back.
Send the customer’s message
POST /conversations/{conversationId}/messages with the text. You get the answer, its sources, and whether it was answered or needs a person. Add Accept: text/event-stream to stream it.
Receive events
Add a webhook URL, verify the signature on every request, and deduplicate on the event id.
API key scopes
| Scope | Allows |
|---|---|
| agents.chat | List agents, start conversations, send and read messages |
| whatsapp.read | List linked numbers, their contacts and send status |
| whatsapp.send | Send messages, cancel a send, and hand a chat to a person or back to the agent |
| whatsapp.contacts | Save and remove contacts, and check whether a phone is on WhatsApp |
Linked numbers need API access turned on for that number. The connection is unofficial and Meta may restrict the number.
Built for real systems
- An Idempotency-Key on every write, so a retry never sends a message twice.
- Error messages in Arabic or English, following Accept-Language.
- Clear rate limits, with Retry-After when you reach them.
- Automatic webhook retries, with delivery history in the dashboard.
- Your keys, webhook URLs and secrets are never written to logs.
FAQ
Common questions
Does Gental have a chatbot API?
Yes. The API channel lets your system start conversations with the agent, send messages and get answers over REST or streamed, and receive events through signed webhooks.
Which plan includes the API?
Growth, Business and Enterprise. Each API answer counts as a reply, like on every channel. See the pricing page for details.
Can I call the API from the browser?
No. Keep the key on your server: your app or site talks to your server, and your server talks to Gental.
How do I know a webhook came from Gental?
Each request carries an HMAC-SHA256 signature of the timestamp and raw body with your signing secret. Reject any request with a wrong signature or a timestamp more than 5 minutes old.
Do API conversations show up for my team?
Yes. They appear in the team inbox like any channel, and a teammate can take over.
Keep reading
- IntegrationsThe knowledge sources, tools and channels your agent connects to today, and what’s next.
- WhatsApp Linked NumberLink a regular WhatsApp number by QR to answer chats and catch requests in groups.
- Human handoff and inboxThe agent hands over to your team, and your team replies from a shared inbox on the same channel.
- Data privacyWhere your data is stored, what reaches the model provider, and how we protect it.
- AI employeeAn AI employee that answers customers and staff from your knowledge, and hands over when needed.
Meet your gentle agent
Build your first agent on your own documents today. Free to start.