The Public API lets your own tools read comments and conversations from VivaDialog and reply to them. It comes with every paid plan. Owners and admins manage API keys under Settings, in the API keys card.
Create a key
- Open Settings and find API keys.
- Type a Key name, for example
CRM sync, and click Create key. - Copy the Access key and the Secret, then click I have copied them.
The secret is shown only once. VivaDialog keeps a hash of it, not the secret itself, so nobody can show it to you again. The list shows each key’s name, the first characters of its access key (“Starts with rpk_…”), and when it was last used.
- Regenerate key & secret gives the key a new access key and a new secret. The old pair stops working at once, so update every tool that uses the key, including a Zapier connection.
- Revoke stops the key for good. It stays in the list marked Revoked, and calls with it are refused.
A key belongs to the workspace, not to the person who created it.
Make a call
Base URL: https://api.vivadialog.com/public
Send the access key as the username and the secret as the password, with HTTP Basic auth:
curl -u "rpk_...:rps_..." https://api.vivadialog.com/public/meCall the API from your server. Browsers on other sites cannot call it, and a secret in a web page is visible to anyone.
Endpoints
| Method and path | What it does |
|---|---|
GET /me |
The workspace the key belongs to: id, name, slug. Good for checking a key. |
GET /entitlements |
The workspace’s plan, status, and limits. |
GET /account |
Your connected channels: platform, display name, status, last sync. |
GET /comment |
Comments, newest first. |
POST /comment/{id}/reply |
Posts a public reply under a comment. Body: {"text": "..."}. |
PATCH /comment/{id} |
Sets a comment’s status. Body: {"status": "pending"}, "resolved", or "ignored". |
GET /conversations |
DM conversations. |
GET /conversations/{id}/messages |
Messages in one conversation, oldest first within each page. |
POST /conversations/{id}/messages |
Sends a DM in a conversation. Body: {"text": "..."}. |
GET /comment takes these optional query parameters: status (pending, resolved, ignored), platform (facebook, instagram, threads), accountId, page, and limit. List endpoints return docs, totalDocs, page, limit, and totalPages. page starts at 1, and limit runs from 1 to 100, 20 by default.
Replies through the API and your quota
A reply or DM sent with an API key counts toward your plan’s monthly conversation quota, the same as a reply from an automation. Replies your users write by hand in the inbox never count. When the quota is used up, the API refuses to send until it resets. See what counts as a conversation.
Meta’s limits apply here too. A DM can go out only within 24 hours of the customer’s last message, and a comment on a live video takes no public reply.
Rate limit
Each key can make 100 requests per minute. This limit may still change. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Past the limit you get 429 with a Retry-After header in seconds.
Errors
Errors come back as JSON with a code and a message.
| Status | code |
Meaning |
|---|---|---|
| 401 | unauthorized |
Missing, wrong, or revoked key or secret. |
| 403 | plan_required |
The workspace has no paid plan. |
| 403 | read_only |
The plan ended, so nothing can be sent or changed. See the free trial and read-only mode. |
| 400 | empty_text |
The reply text is empty. |
| 400 | invalid_status |
status is not pending, resolved, or ignored. |
| 404 | not_found |
No comment or conversation with that id in this workspace. |
| 409 | account_paused |
The channel is paused, so nothing can be sent from it. |
| 422 | live_comment |
A live video comment, which takes no public reply. |
| 422 | outside_messaging_window |
More than 24 hours since the customer’s last message. |
| 429 | rate_limited |
Too many requests this minute. |
| 429 | quota_exceeded |
The monthly conversation quota is used up. |
| 429 | threads_publish_throttled |
Threads allows one reply per channel every 30 seconds. Wait for Retry-After. |
| 502 | reply_failed, send_failed |
The platform refused the reply. |
To have VivaDialog tell your tool about new comments and DMs instead of asking every few minutes, see outgoing webhooks.