Learn when to use the AI SNS CHAT REST API, how keys, streaming and signed webhooks work, and how to build safely on top of website chat and WhatsApp.
Out-of-the-box channels cover a lot, but sooner or later a team wants something specific: a chat inside its own mobile app, a reply that shows up in an internal tool, or an alert in a system nobody else uses. The REST API is how you reach beyond the dashboard. This article explains what the API is good for, how to think about security and limits, and how to plan an integration that does not become a maintenance burden.
When the API is the right tool (and when it is not)
Before writing any code, check whether you need it. AI SNS CHAT already ships a long list of ready-made channels, including the chat widget, WhatsApp, Messenger, Instagram, Telegram, Slack and Microsoft Teams, plus Zapier and many connectors. If your need is "put the agent on WhatsApp", a few clicks in the dashboard will do it.
The API makes sense when:
- You have your own front end, such as a native app, a kiosk or a customer portal, and want the agent to answer inside it.
- You want conversation events to flow into your own systems in real time.
- You need the agent's reply to stream into a custom interface as it is written.
- You are building an internal tool that talks to an agent on behalf of staff.
It is probably not the right tool when a built-in channel, an Action or a Zapier connection already does the job. Less code means fewer things to maintain.
The building blocks
The public API is JSON over REST. Three ideas matter most.
API keys
Keys are created in the workspace settings. Each key is shown once, at creation, so store it in a secrets manager straight away. Keys can be revoked at any time, and API access requires the Hobby plan or higher.
Treat a key like a password:
- Keep it on your server, never in browser code or a mobile app bundle.
- Use a separate key per integration so you can revoke one without breaking the others.
- Rotate keys when someone with access leaves the team.
Streaming replies
For chat, waiting for a full answer can feel slow. The API supports server-sent events (SSE) streaming: pass stream=1 and the reply arrives in pieces, so your interface can show text as it is generated, much like the website widget does.
Signed webhooks
In the other direction, AI SNS CHAT can call your server when something happens. Webhooks are signed with HMAC, and there is a delivery log so you can see what was sent and whether it arrived. The signature lets your server confirm that a request really came from AI SNS CHAT and was not forged.
- 01Your app or site
- 02Your server (holds the API key)
- 03AI SNS CHAT agent
- 04Signed webhook back to your server
Respect the published rate limits
The API reference publishes limits, and your design should stay well inside them:
| Area | Published limit |
|---|---|
| Authentication | 20 requests per 5 minutes per IP |
| Public chat | 30 per minute per IP |
| Polling | 120 per minute |
Two practical consequences follow.
First, prefer webhooks or streaming to tight polling loops. If you poll for new messages, do it at a sensible interval and back off when you get a limit response.
Second, remember that limits are per IP. If all your traffic comes from one server, that server shares one allowance. A public-facing site where many visitors chat directly is a different pattern from a back-end service relaying requests, so test the pattern you actually plan to run.
Design patterns that work
Pattern 1: your own chat front end
Build the interface you want, send each visitor message from your server to the agent, and stream the reply back. Your server decides who is allowed to chat and keeps the key hidden.
Pattern 2: events into your own systems
Subscribe a webhook endpoint to the events you care about. Verify the HMAC signature on every request, respond quickly, and do the heavy work in a background job. If your endpoint is down, the delivery log helps you see what you missed.
Pattern 3: a thin layer over a messaging channel
A customer might start on website chat and continue on WhatsApp or Messenger. The channels themselves are configured in the dashboard, while your own system can use the API to reach the same agent for internal purposes, such as a staff-facing lookup tool. Keep the channel setup and the custom code separate so each can change independently.
Security checklist before you go live
Most API incidents come from a few avoidable mistakes.
- Keep keys server-side. If a key ever appears in client code, revoke it and issue a new one.
- Verify every webhook signature. Reject anything that fails the check.
- Make handlers idempotent. A webhook can arrive more than once; processing it twice should not create duplicate records.
- Log carefully. Do not write keys or customer personal data to logs you do not need.
- Plan for failure. Decide what your app shows when the agent is slow or a request is rate limited.
- Limit who can create keys. Workspace roles and the activity log help here, since the log records creates and edits with name, email and time.
AI SNS CHAT itself applies protections such as AES-256-GCM encryption for stored secrets, optional two-factor authentication, and per-agent filters against prompt injection and abuse. Its practices are designed with reference to GDPR and APPI, and the site states clearly that it is not SOC 2, ISO 27001 or HIPAA certified. Your own integration should carry its share of the responsibility, especially for the personal data your systems store.
Testing and rollout
A calm rollout saves a lot of stress.
- Test in the Playground first. Confirm the agent answers the way you want before connecting code to it.
- Use a duplicate agent for experiments. Duplicating copies persona, model and training data, but not conversations, so you can try changes without touching the live agent.
- Start with a small slice of traffic. For example, if a shop receives 300 chats a month, route a few dozen through the new integration first and review them in the chat logs.
- Watch credit use. One reply costs one credit, so a runaway loop in your code can spend credits quickly. Check the Usage page after your first day.
- Keep restore points in mind. Agents have restore points, so a bad persona change can be rolled back while you debug your side.
Doing this in AI SNS CHAT
Here is a practical path from zero to a working integration.
- Check your plan. API keys need Hobby or higher. If you are on Free, compare plans on the pricing page.
- Prepare the agent. Create or choose an agent, add its knowledge under Data sources, and test it in the Playground. Model choices live under Agent → Settings → AI. Advanced models and model fallback need Hobby or higher.
- Create a key. Open Workspace settings → API keys, create a key for this one integration, and copy it immediately. It is shown only once.
- Read the API reference. It documents the endpoints, the
stream=1option for SSE, the webhook format and the published rate limits. - Set up webhooks. Register your endpoint, verify the HMAC signature in your code, and use the delivery log to confirm that events arrive.
- Brand it your way. If your integration involves a shareable page or embed, Agent → Settings → Custom domains lets you serve the embed script, iframe and agent link from your own subdomain through a CNAME that is verified by DNS lookup (Hobby or higher).
- Review conversations. Conversations on non-email channels appear in Activity → Chat logs, where you can filter, flag, rate with thumbs up or down, and edit a reply into the ideal answer to train the agent. The Inbox is email-only.
- Hand off to people when needed. Helpdesk → Scheduling (Standard or higher) assigns handoffs to whoever is on shift, with alerts to Slack, Teams, LINE WORKS, WhatsApp, email or a webhook.
If you ever get stuck, Synthia, the built-in AI fleet manager, can answer product questions and walk you to the right screen. To see everything the platform offers beyond the API, browse the features page, and for the channel list see connections. Security details are on the security page.
Conclusion
The REST API is best treated as a precision tool. Use dashboard channels and connectors for the common cases, and keep custom code for what only your business needs. Keep keys on the server, verify webhook signatures, respect the published rate limits, and roll out gradually while watching chat logs and credit use. Done this way, an API integration stays small, safe and easy to change.
Frequently asked questions
Which plan do I need to use the REST API?
API keys require the Hobby plan or higher. Keys are created in Workspace settings → API keys, are shown only once, and can be revoked at any time.
Can I stream replies into my own interface?
Yes. The API supports server-sent events: add stream=1 to the request and the reply arrives progressively, so your interface can display text as it is generated.
How do I know a webhook really came from AI SNS CHAT?
Webhooks are HMAC-signed. Your server should recompute and compare the signature on every request and reject anything that does not match. The delivery log shows what was sent so you can troubleshoot missed events.
What are the rate limits?
The API reference publishes them: authentication is 20 requests per 5 minutes per IP, public chat is 30 per minute per IP, and polling is 120 per minute. Prefer webhooks and streaming over tight polling loops to stay comfortably inside them.
Do I need the API to put an agent on WhatsApp or Messenger?
No. Those are built-in channels you set up from the Channels section of the dashboard. The API is for custom work, such as your own app, portal or internal tools.


