Aelyst API Documentation
Overview
Section titled “Overview”The Aelyst Developer API lets you integrate omnichannel messaging, AI agents, and automation into your own platforms and applications. The API covers sending and receiving messages across WhatsApp, Instagram, Facebook, Threads and TikTok, managing contacts and conversations, running broadcasts, and triggering workflow automations — so you can build tailored customer-engagement experiences on top of Aelyst.
The API is built around REST principles. It uses standard HTTP methods (GET, POST, PUT, DELETE), encodes request and response bodies as JSON, follows standard HTTP status codes, and requires authentication on every request.
The base URL for all API requests is api.aelyst.ai/v1, and all requests must be made over HTTPS.
Authentication
Section titled “Authentication”An API Access Token authenticates your requests. You can view and manage tokens in your workspace under Settings > Integrations > Developer API.
The token is passed in the Authorization header on every request as a Bearer token:
Authorization: Bearer YOUR_ACCESS_TOKENKeep your access tokens secret. Do not embed them in client-side code or commit them to version control.
Rate Limiting
Section titled “Rate Limiting”The Aelyst API is rate limited to protect platform stability. Limits are applied per workspace and per endpoint.
Each API method is limited to 5 requests per second per unique request path.
Responses include headers so you can track your remaining quota:
| Header | Description |
|---|---|
Retry-After |
Seconds to wait before retrying the request |
X-RateLimit-Limit |
Requests allowed for this endpoint |
X-RateLimit-Remaining |
Requests remaining for this endpoint |
When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header. Use it to determine when it is safe to retry.
Rate Limit Scope
Section titled “Rate Limit Scope”Rate limits are enforced per HTTP method and per unique request path, where the path includes path parameters. For example, /v1/contact/1 and /v1/contact/2 count as different paths.
Limits are tracked independently for each method + path combination. Hitting the limit on GET /v1/contact/1 does not block GET /v1/contact/2 or POST /v1/contact. Only the specific combination that exceeds the limit is temporarily restricted.
HTTP Response Codes
Section titled “HTTP Response Codes”| Status Code | Description |
|---|---|
| 200 OK | The request succeeded and a response was returned. |
| 201 Created | The request succeeded and a new resource was created. |
| 400 Bad Request | The request was invalid — for example, a malformed contact email, phone, or ID. |
| 401 Unauthorized | The access token is missing or invalid. |
| 403 Forbidden | Access was denied, usually for security reasons. |
| 404 Not Found | The resource does not exist for the given access token. |
| 429 Too Many Requests | You exceeded the rate limit. Slow down and retry after the Retry-After interval. |
| 500 Internal Server Error | Something went wrong on our end. |
| 502 / 504 | An upstream/gateway timeout occurred. |
| 503 Service Unavailable | The server is overloaded or under maintenance. |
Pagination
Section titled “Pagination”List endpoints return results in pages rather than all at once. Use the cursor returned in pagination.next to request the next page, or pagination.previous for the previous one.
| Param | Type | Description |
|---|---|---|
cursorId |
integer | (optional) A cursor from a previous response. Default: start of the list. |
limit |
integer | (optional) Items to return. Default: 10. Max: 100. |
Integrations & Extensibility
Section titled “Integrations & Extensibility”Aelyst is built to connect with your existing stack — whether you’re wiring up external systems, receiving real-time events, or driving AI-powered automation.
Channels
Section titled “Channels”Aelyst connects to messaging and social channels through its integration layer: WhatsApp and LinkedIn via Unipile, and Instagram, Facebook, Threads, and TikTok Ads via Zernio. Once a channel is connected in your workspace, its conversations and contacts are available through the same unified API.
Webhooks
Section titled “Webhooks”Webhooks push real-time notifications to your server whenever events occur in your workspace — new messages, contact updates, conversation stage changes, and more. Instead of polling, your systems stay in sync automatically.
You can use webhooks to:
- Trigger workflows in external systems when new messages arrive.
- Sync CRM or data-warehouse records when contact data changes.
- Automate follow-ups and monitoring in real time.
Events are delivered as structured JSON over HTTPS, with signing secrets so you can verify authenticity.
AI Agents
Section titled “AI Agents”Aelyst’s AI Agents can be configured and driven through the API — connecting knowledge sources, defining HTTP actions, scheduling follow-ups, and handling voice transcription and payment (QRIS/QR) rendering. Use the API to test agent responses, manage configurations, and integrate agent behavior into your own product flows.
👉 View AI Agents Documentation
Broadcasts & Workflows
Section titled “Broadcasts & Workflows”Programmatically create broadcast campaigns and trigger workflow automations. Build audiences, schedule sends, and let workflows react to events across the customer lifecycle — all from the API.
👉 View Automation Documentation
Get Started
Section titled “Get Started”You’re ready to start building with Aelyst. Choose your next step: