Developer API
Integrate contacts, conversations, messages, and webhooks with Ricky.
Ricky's stable REST API is at https://getricky.ai/api/v1. The OpenAPI contract describes every route, parameter, and response.
Get started
- An organization administrator opens Settings → Organization → Developer API.
- Create a key with the minimum scopes and an expiry. Copy the secret when shown; Ricky displays it only once.
- Send
Authorization: Bearer rky_live_…from your server. Never place a key in browser code or a URL.
curl 'https://getricky.ai/api/v1/contacts?page_size=20' \
-H 'Authorization: Bearer YOUR_KEY'Keys belong to one organization. Revocation, expiry, or removing the creator's organization management permission ends access. Revoke a key from the same settings page.
Resources
| Resource | Routes | Scopes |
|---|---|---|
| Contacts | GET/POST /contacts, GET/PATCH /contacts/{id} | contacts:read, contacts:write |
| Conversations | GET /conversations, GET /conversations/{id}, PATCH /conversations/{id}/assignment, POST /conversations/{id}/close, POST /conversations/{id}/reopen | conversations:read, conversations:write |
| Messages | GET/POST /conversations/{id}/messages | conversations:read, messages:send |
| Catalogs | GET /members, GET /tags, GET /templates | members:read, tags:read, templates:read |
| Webhooks | GET/POST /webhooks, DELETE /webhooks/{id}, GET /webhooks/{id}/deliveries, POST /webhooks/{id}/deliveries/{deliveryId}/retry | webhooks:manage |
All routes are under /api/v1. Responses use JSON. Errors contain error.code and error.message. Include X-Request-Id when contacting support.
Pagination, limits, and retries
Contact and conversation lists accept page_size from 1 to 100 and return next_cursor. Pass that opaque cursor to the next request. Member, tag, and template routes return the organization's full catalog. A webhook's delivery list shows its latest 100 deliveries.
Each key allows 120 requests per minute. A 429 response includes Retry-After. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix seconds).
Contact and conversation changes and message sends require an Idempotency-Key header of 8–200 characters. Reuse it only for an exact retry of the same method, URL, and body. Replayed responses include Idempotency-Replayed: true. If the outcome is uncertain, Ricky returns 409 request_processing: inspect the resource and contact support with X-Request-Id before creating a new operation. Creating/disabling webhook subscriptions and retrying deliveries do not require this header.
Sending a message returns 202 when Ricky accepts the work. It does not mean the channel provider delivered it. Read the conversation for its later status. Channel restrictions, including the WhatsApp window, still apply.
Webhooks
Subscribe to message.received, message.sent, conversation.opened, conversation.closed, or conversation.assignment_changed. The destination must be public HTTPS. Creation returns signing_secret once. Store it on your server.
Each delivery contains id, type, occurred_at, organization_id, and data with id and conversation_id. Ricky sends X-Ricky-Delivery-Id, X-Ricky-Timestamp, and X-Ricky-Signature. The signature is v1= followed by the hexadecimal HMAC SHA-256 of timestamp + "." + exact JSON body, keyed with the webhook secret. Compare it in constant time and reject timestamps more than five minutes old.
Respond with any 2xx status within ten seconds. Ricky retries failures up to ten times with increasing delays. Deliveries can repeat; deduplicate by X-Ricky-Delivery-Id. Read /webhooks/{id}/deliveries for results and use the retry route for a failed delivery. Disabling a subscription stops pending and new deliveries.