# Ricky Help Center > Guides to set up agents, WhatsApp, Instagram, integrations and conversations in Ricky. Each link points to the page as Markdown. Every page in one file: https://getricky.ai/en/llms-full.txt. En español: https://getricky.ai/llms.txt. - Help center: Set up and run Ricky - [Help center](https://getricky.ai/en/docs.md): Get started with Ricky and learn how to serve your customers on WhatsApp, Instagram and Messenger. - Getting started - [Get started with Ricky](https://getricky.ai/en/docs/primeros-pasos.md): Create your account, connect a channel, get your first message and invite your team. - [Team and settings](https://getricky.ai/en/docs/primeros-pasos/equipo.md): Invite people, manage their access and configure your account and organization. - [Billing and credits](https://getricky.ai/en/docs/primeros-pasos/facturacion.md): Review your subscription, your usage and what happens when your AI credits run out. - Channels - [Channels](https://getricky.ai/en/docs/canales.md): Connect WhatsApp, Instagram, and Messenger to the shared inbox. - [Connect WhatsApp](https://getricky.ai/en/docs/canales/whatsapp.md): Connect a WhatsApp Business number and check its status. - [Connect Instagram](https://getricky.ai/en/docs/canales/instagram.md): Connect an Instagram professional account to handle direct messages. - [Connect Messenger](https://getricky.ai/en/docs/canales/messenger.md): Connect a Facebook Page to receive and reply to direct messages. - [Add a chat to your website](https://getricky.ai/en/docs/canales/chat-web.md): Put Ricky's web chat on your public website or on your team's internal site. - Agents - [Set up an agent](https://getricky.ai/en/docs/agentes.md): Define how an agent should reply and which actions it can take. - [Agent tools](https://getricky.ai/en/docs/agentes/herramientas.md): Choose what an agent can read and what actions it can perform. - [Human handoff](https://getricky.ai/en/docs/agentes/paso-a-humano.md): Let an agent assign a conversation to a person and keep answering until someone takes it. - [Buttons and interactive messages](https://getricky.ai/en/docs/agentes/botones-interactivos.md): Let the agent offer tappable choices on WhatsApp and Instagram. - [Voice notes](https://getricky.ai/en/docs/agentes/notas-de-voz.md): Receive customer audio and send recordings from a conversation. - [AI voice calls](https://getricky.ai/en/docs/agentes/llamadas-de-voz.md): Set the agent voice for calls on an eligible WhatsApp number. - [Business knowledge](https://getricky.ai/en/docs/agentes/conocimiento.md): Organize the locations and contacts your team can share with customers. - [Knowledge files](https://getricky.ai/en/docs/agentes/archivos.md): Upload documents and images that agents can consult or send. - [Shareable contacts](https://getricky.ai/en/docs/agentes/directorio.md): Store people or departments the agent may recommend to customers. - [Business locations](https://getricky.ai/en/docs/agentes/ubicaciones.md): Keep addresses and opening hours the agent can share. - Integrations - [Integrations](https://getricky.ai/en/docs/integraciones.md): Connect the systems an agent can look up or update. - [Connect Meta Ads](https://getricky.ai/en/docs/integraciones/meta-ads.md): See what each Meta ad spent next to the conversations it brought. - [Connect n8n](https://getricky.ai/en/docs/integraciones/n8n.md): Authorize n8n workflows for an agent to run. - [Connect Odoo](https://getricky.ai/en/docs/integraciones/odoo.md): Manage the private connection to your business's Odoo appointment system. - [Connect Zoho CRM and Zoho Inventory](https://getricky.ai/en/docs/integraciones/zoho.md): Authorize each Zoho product separately and choose the agent's tools. - [Connect Google Drive](https://getricky.ai/en/docs/integraciones/google-drive.md): Let an agent search files available to the connected Google account. - WhatsApp - [WhatsApp](https://getricky.ai/en/docs/whatsapp.md): Connect a number, manage templates, and prepare broadcasts. - [WhatsApp templates](https://getricky.ai/en/docs/whatsapp/plantillas.md): Create and review WhatsApp-approved templates for messages outside the 24-hour window. - [WhatsApp broadcasts](https://getricky.ai/en/docs/whatsapp/envios-masivos.md): Send a template to many contacts at once and check who received it. - Operations - [Handle conversations](https://getricky.ai/en/docs/operacion/conversaciones.md): Review messages, assign owners or agents and reply manually. - [Calls](https://getricky.ai/en/docs/operacion/llamadas.md): Review every WhatsApp call to your numbers, who answered and what was said. - [Quick replies](https://getricky.ai/en/docs/operacion/respuestas-rapidas.md): Save text your team reuses when replying and fill it in without typing it again. - [Contacts and CRM](https://getricky.ai/en/docs/operacion/contactos.md): Save and organize your customers' information, with tags, fields and notes. - [Create a workflow](https://getricky.ai/en/docs/operacion/workflows.md): Define when a conversation starts and which steps the bot follows. - [Read your reports](https://getricky.ai/en/docs/operacion/reportes.md): Understand how many people write to you, whether you serve them well, what your team does, your broadcasts and your ads. - [Work with the Ricky assistant](https://getricky.ai/en/docs/operacion/asistente.md): Look up your data and ask for actions on conversations, the CRM, agents and workflows. - Settings - [Settings](https://getricky.ai/en/docs/configuracion.md): Manage your account, organization, team, and email reports and alerts. - [Your profile and sign-in](https://getricky.ai/en/docs/configuracion/perfil.md): Update personal details, sign-in methods, and password. - [Use Ricky from Claude or ChatGPT](https://getricky.ai/en/docs/configuracion/conector.md): Connect an external assistant with your account permissions. - [Organization details](https://getricky.ai/en/docs/configuracion/organizacion.md): Change the workspace name and the brand shown in its menu. - [Manage the team](https://getricky.ai/en/docs/configuracion/equipo.md): Invite members, change roles, and remove access. - [Email reports](https://getricky.ai/en/docs/configuracion/reportes-por-correo.md): Schedule a recurring report for team members. - Help - [Frequently asked questions](https://getricky.ai/en/docs/ayuda/preguntas-frecuentes.md): Short answers about channels, agents, human control, integrations and billing. - [Troubleshooting](https://getricky.ai/en/docs/ayuda/solucionar-problemas.md): Check connections, assignments and statuses when Ricky doesn't receive or reply to messages. - [Instagram won't let Ricky reply](https://getricky.ai/en/docs/ayuda/instagram-control-conversaciones.md): Check the default app and conversation control when Instagram blocks a reply from Ricky. - [Coverage while the team is away](https://getricky.ai/en/docs/ayuda/cobertura-del-agente.md): Schedule an agent to answer every chat during a closure, without changing who each chat is assigned to. - API: REST API and webhooks - [Introduction](https://getricky.ai/en/docs/api.md): Connect your systems to your organization's contacts, conversations and messages. - [Changelog](https://getricky.ai/en/docs/api/changelog.md): Versions and changes of the Ricky API. - **Guides** - [Authentication](https://getricky.ai/en/docs/api/authentication.md): Create keys with the fewest scopes and send them from your server. - [Errors](https://getricky.ai/en/docs/api/errors.md): The shape of error responses and the code catalog. - [Pagination](https://getricky.ai/en/docs/api/pagination.md): Walk lists with page_size, cursor and next_cursor. - [Idempotency, rate limits and retries](https://getricky.ai/en/docs/api/idempotency-and-rate-limits.md): Repeat writes without duplicating effects, and stay within the request limit. - [Sending messages](https://getricky.ai/en/docs/api/sending-messages.md): Start WhatsApp conversations with templates, follow each send, and reply with text or files inside the reply window. - [Webhooks](https://getricky.ai/en/docs/api/webhooks.md): Receive signed events from Ricky, verify them and process each one once. - [Workflows](https://getricky.ai/en/docs/api/workflows.md): Create, edit, activate and pause the organization's workflows, and review their executions. - [Reports](https://getricky.ai/en/docs/api/reports.md): Read the numbers of the Reports pages for a period, with the same filters. - [Agents and knowledge](https://getricky.ai/en/docs/api/agents-and-knowledge.md): Create AI agents, put them on conversations and keep the information they share up to date. - [Tags, fields, search and quick replies](https://getricky.ai/en/docs/api/crm-and-inbox.md): Organize contacts with tags and fields, search the inbox, mark conversations read and manage quick replies. - [Inbox](https://getricky.ai/en/docs/api/inbox.md): Filter conversations as the inbox does, assign them in bulk, resolve handoffs, mark them unread, quote messages and fetch received files. - [WhatsApp templates and numbers](https://getricky.ai/en/docs/api/whatsapp.md): Create, validate, edit and delete WhatsApp templates, follow Meta's review, fill their variables from contact fields and manage your numbers. - [Broadcasts](https://getricky.ai/en/docs/api/broadcasts.md): Send an approved WhatsApp template to many numbers, now or at a set time, and follow each delivery. - **Contacts** - [List contacts](https://getricky.ai/en/docs/api/reference/contacts/list-contacts.md): Most recently updated first. Filters combine. Scope: `contacts:read`. - [Create a contact](https://getricky.ai/en/docs/api/reference/contacts/create-contact.md): Creates a CRM contact. It does not message anyone; to reach a phone, start a conversation. Scope: `contacts:write`. - [Get a contact](https://getricky.ai/en/docs/api/reference/contacts/get-contact.md): One contact with its tags, identities and custom values. Scope: `contacts:read`. - [Update a contact](https://getricky.ai/en/docs/api/reference/contacts/update-contact.md): Changes only the fields in the body. `tag_ids` replaces the whole tag set; `custom_values` merges by key. Scope: `contacts:write`. - [Add a note to a contact](https://getricky.ai/en/docs/api/reference/contacts/add-contact-note.md): Adds text after the current `notes`, separated by a blank line, and answers the contact. To replace the notes, update the contact. Scope: `contacts:write`. - [List contact fields](https://getricky.ai/en/docs/api/reference/contacts/list-contact-fields.md): The custom fields whose IDs key `custom_values`. Scope: `contacts:read`. - [Create a contact field](https://getricky.ai/en/docs/api/reference/contacts/create-contact-field.md): Adds a custom field to every contact, after the existing ones. A name already in use, in any case, answers `409 conflict`. Scope: `contacts:write`. - [Change tags on many contacts](https://getricky.ai/en/docs/api/reference/contacts/change-contacts-tags.md): Adds and removes the same tags on up to 100 contacts and answers one result per contact, in order. A tag ID the organization does not have refuses the whole request before any contact changes. Scope: `contacts:write`. - [Delete a contact field](https://getricky.ai/en/docs/api/reference/contacts/delete-contact-field.md): Deletes the field and its value on every contact, and answers the field as it was. It cannot be undone. Scope: `contacts:write`. - **Conversations** - [List conversations](https://getricky.ai/en/docs/api/reference/conversations/list-conversations.md): Latest activity first. The filters are the inbox's and combine with each other; send the same ones with `cursor`. Scope: `conversations:read`. - [Start a conversation](https://getricky.ai/en/docs/api/reference/conversations/start-conversation.md): Sends an approved WhatsApp template to a phone number. Ricky finds or creates the contact and reuses the number's conversation on that channel. Answers `202`: the send is queued; follow it with `GET /sends/{send_id}`. Scope: `messages:send`. - [Get a conversation](https://getricky.ai/en/docs/api/reference/conversations/get-conversation.md): One conversation. Scope: `conversations:read`. - [Assign a conversation](https://getricky.ai/en/docs/api/reference/conversations/assign-conversation.md): Makes a member responsible for the conversation, or unassigns it. Scope: `conversations:write`. - [Close a conversation](https://getricky.ai/en/docs/api/reference/conversations/close-conversation.md): Closing an already closed conversation changes nothing. Scope: `conversations:write`. - [Reopen a conversation](https://getricky.ai/en/docs/api/reference/conversations/reopen-conversation.md): Reopening an open conversation changes nothing. Send no body. Scope: `conversations:write`. - [Set the AI agent of a conversation](https://getricky.ai/en/docs/api/reference/conversations/assign-conversation-agent.md): Makes an agent answer the conversation, or turns the AI off with `null`. Either way the conversation is no longer assigned to a member. Scope: `conversations:write`. - [Search conversations](https://getricky.ai/en/docs/api/reference/conversations/search-conversations.md): Conversations whose contact or messages contain the text, latest activity first. Answers one page of at most `limit`; `next_cursor` is always null. Scope: `conversations:read`. - [Change the tags of a conversation's contact](https://getricky.ai/en/docs/api/reference/conversations/change-conversation-tags.md): Tags belong to the conversation's contact, not to the conversation: this adds and removes tags on that contact, so every conversation of the contact shows them, and answers the contact. The change is a `contact.tags_changed` webhook event; there is no conversation tag event. Scope: `contacts:write`. - [Mark a conversation read](https://getricky.ai/en/docs/api/reference/conversations/mark-conversation-read.md): Marks it read for the whole team through its latest message, as opening it in the inbox does. On WhatsApp the contact sees the read receipt. Send no body. Scope: `conversations:write`. - [Mark a conversation unread](https://getricky.ai/en/docs/api/reference/conversations/mark-conversation-unread.md): Marks it unread for the whole team, as the inbox does. The contact sees nothing. Send no body. Scope: `conversations:write`. - [Assign many conversations](https://getricky.ai/en/docs/api/reference/conversations/assign-conversations.md): Makes members responsible for up to 100 conversations, as assigning each one does, and answers one result per conversation, in order. A member outside the organization refuses the whole request before any conversation changes. Scope: `conversations:write`. - [Resolve a handoff](https://getricky.ai/en/docs/api/reference/conversations/resolve-conversation-handoff.md): Ends the conversation's `active_handoff` as the inbox does: back to the AI agent that asked for it, or with the member. A conversation with no handoff waiting answers `422 rule_violation`, and so does `returned_to_ai` when no AI agent asked for it. Scope: `conversations:write`. - **Messages** - [List messages](https://getricky.ai/en/docs/api/reference/messages/list-messages.md): Newest first. Scope: `conversations:read`. - [Send a message](https://getricky.ai/en/docs/api/reference/messages/send-message.md): Sends text, a file on WhatsApp or Instagram, or a template on WhatsApp. For a file, Ricky downloads `media.url` before answering. Answers `202`: the send is queued; follow it with `GET /sends/{send_id}`. A `message.sent` webhook fires once the provider accepts it. Scope: `messages:send`. - [Get a message](https://getricky.ai/en/docs/api/reference/messages/get-message.md): One message, as the list shows it. A media `url` is signed again on each read. Scope: `conversations:read`. - [Get a send](https://getricky.ai/en/docs/api/reference/messages/get-send.md): Whether the provider accepted a message, and why not if it failed. Scope: `messages:send`. - [Search messages](https://getricky.ai/en/docs/api/reference/messages/search-messages.md): Messages of every conversation that contain the words, newest first. Answers one page of at most `limit`; `next_cursor` is always null. Scope: `conversations:read`. - [Fetch a message's file](https://getricky.ai/en/docs/api/reference/messages/fetch-message-media.md): Ricky stores the file of each message it receives in the background, and `media.url` is null until it has. This stores it now from the provider and answers the message with its `url`; a file already stored answers at once. A message without a received file, or whose file the provider says expired (it keeps them about 30 days), answers `422 rule_violation`; other provider failures answer `502 upstream_error`. Send no body. Scope: `conversations:read`. - **Catalogs** - [List channels](https://getricky.ai/en/docs/api/reference/catalogs/list-channels.md): WhatsApp numbers, Instagram accounts and Facebook pages. Scope: `conversations:read`. - [List members](https://getricky.ai/en/docs/api/reference/catalogs/list-members.md): People in the organization; their IDs assign conversations and own contacts. Scope: `members:read`. - [List tags](https://getricky.ai/en/docs/api/reference/catalogs/list-tags.md): Contact tags. Scope: `tags:read`. - [Create a tag](https://getricky.ai/en/docs/api/reference/catalogs/create-tag.md): Creates a contact tag. Apply it with `tag_ids` on a contact. A name already in use, in any case, answers `409 conflict`. Scope: `tags:write` or, on older keys, `contacts:write`. - [Update a tag](https://getricky.ai/en/docs/api/reference/catalogs/update-tag.md): Renames or recolors a tag on every contact that has it. A name already in use, in any case, answers `409 conflict`. Scope: `tags:write`. - [Delete a tag](https://getricky.ai/en/docs/api/reference/catalogs/delete-tag.md): Deletes the tag and removes it from every contact, and answers the tag as it was. It cannot be undone. Scope: `tags:write`. - **Webhooks** - [List webhooks](https://getricky.ai/en/docs/api/reference/webhooks/list-webhooks.md): Newest first, at most 100. Scope: `webhooks:manage`. - [Create a webhook](https://getricky.ai/en/docs/api/reference/webhooks/create-webhook.md): The response carries `signing_secret`, the only time Ricky shows it. Scope: `webhooks:manage`. - [Disable a webhook](https://getricky.ai/en/docs/api/reference/webhooks/disable-webhook.md): Stops new and pending deliveries. Disabling twice answers `404`. Scope: `webhooks:manage`. - [Send a test event](https://getricky.ai/en/docs/api/reference/webhooks/test-webhook.md): Sends one signed `webhook.test` event to the endpoint now and answers what it replied. It is not recorded as a delivery and is not retried. Scope: `webhooks:manage`. - [Rotate the signing secret](https://getricky.ai/en/docs/api/reference/webhooks/rotate-webhook-secret.md): Returns a new `signing_secret`, the only time Ricky shows it. Until `expire_previous_after_hours` passes, every delivery carries two signatures in `X-Ricky-Signature`, new first, so you can deploy the new secret without missing events. The body is optional. Scope: `webhooks:manage`. - [List deliveries](https://getricky.ai/en/docs/api/reference/webhooks/list-webhook-deliveries.md): The 100 most recent deliveries of a webhook. Scope: `webhooks:manage`. - [Retry a delivery](https://getricky.ai/en/docs/api/reference/webhooks/retry-webhook-delivery.md): Queues a failed delivery again with a fresh attempt budget and sends it at once. Scope: `webhooks:manage`. - **Workflows** - [List workflows](https://getricky.ai/en/docs/api/reference/workflows/list-workflows.md): Every workflow of the organization with its definition, last changed first. Scope: `workflows:read`. - [Create a workflow](https://getricky.ai/en/docs/api/reference/workflows/create-workflow.md): Creates a conversation workflow as a `draft`; it runs nothing until you activate it. Ricky checks the flow with the rules of the workflow editor, and that its channels, members and agents belong to the organization. Scope: `workflows:write`. - [Get a workflow](https://getricky.ai/en/docs/api/reference/workflows/get-workflow.md): One workflow with its definition. Scope: `workflows:read`. - [Update a workflow](https://getricky.ai/en/docs/api/reference/workflows/update-workflow.md): Changes the name, replaces the definition, or both, and keeps the status. An active workflow must still be able to run the new definition. A scheduled workflow only accepts a new name. Scope: `workflows:write`. - [Delete a workflow](https://getricky.ai/en/docs/api/reference/workflows/delete-workflow.md): Deletes the workflow and answers it as it was. Sends already queued still go out. Deleting twice answers `404`. Scope: `workflows:write`. - [Activate a workflow](https://getricky.ai/en/docs/api/reference/workflows/activate-workflow.md): From now on it runs on new events, and its steps can message contacts, assign members or put an AI agent on conversations. Ricky checks again what it references; assigning an AI agent needs an active subscription. Activating an active workflow changes nothing. Send no body. Scope: `workflows:write`. - [Pause a workflow](https://getricky.ai/en/docs/api/reference/workflows/pause-workflow.md): It starts no new executions; sends already queued still go out. Pausing a paused workflow changes nothing. Send no body. Scope: `workflows:write`. - [List executions](https://getricky.ai/en/docs/api/reference/workflows/list-workflow-executions.md): Runs of the workflow with their status, attempts and errors, newest first. Scope: `workflows:read`. - [Set the header file of a scheduled workflow](https://getricky.ai/en/docs/api/reference/workflows/upload-workflow-header-media.md): Downloads the file at `url` and stores it as the header every send of a scheduled workflow carries, replacing the previous one. The workflow’s template must have an image, video or document header, and the file must be that kind. Answers the workflow, with `has_header_image` true. Scope: `workflows:write`. - [Preview appointment reminders](https://getricky.ai/en/docs/api/reference/workflows/preview-workflow-reminders.md): Reads the Odoo appointments an appointment-reminder workflow would message on `date` and says, for each, whether it would be sent and with what text. Sends nothing. Only for workflows with `source.kind` `odoo_appointments`, in an organization with Odoo connected; past days are in the history. Scope: `workflows:read`. - [Get appointment reminder history](https://getricky.ai/en/docs/api/reference/workflows/get-workflow-reminder-history.md): What an appointment-reminder workflow checked in Odoo and sent on `date`, from what Ricky recorded; it does not read Odoo. Scope: `workflows:read`. - [List the Odoo appointment states](https://getricky.ai/en/docs/api/reference/workflows/list-workflow-reminder-states.md): Reads from Odoo, live, every appointment state its installation has: the values an appointment-reminder workflow’s `source.appointment_states` and the preview’s `appointment_states` take. Only for workflows with `source.kind` `odoo_appointments`, in an organization with Odoo connected. Scope: `workflows:read`. - **Reports** - [Get the live dashboard](https://getricky.ai/en/docs/api/reference/reports/get-dashboard-report.md): Open conversations, who holds them and who is waiting for a reply, right now. "Today" is the America/Panama day. Scope: `reports:read`. - [Get the conversations report](https://getricky.ai/en/docs/api/reference/reports/get-conversations-report.md): Customers who wrote in the period, new or returning, per channel, day and hour. Days and hours are America/Panama time, like the Reports pages; each number is compared with the previous period of the same length. Scope: `reports:read`. - [Get the messages report](https://getricky.ai/en/docs/api/reference/reports/get-messages-report.md): Messages received and sent in the period, and who sent them. Days and hours are America/Panama time, like the Reports pages; each number is compared with the previous period of the same length. Scope: `reports:read`. - [Get the responses report](https://getricky.ai/en/docs/api/reference/reports/get-responses-report.md): How fast people and AI agents answered customers in the period, per channel and responder. Days and hours are America/Panama time, like the Reports pages; each number is compared with the previous period of the same length. Scope: `reports:read`. - [Get the resolutions report](https://getricky.ai/en/docs/api/reference/reports/get-resolutions-report.md): Conversations closed in the period and how long they were open. Days and hours are America/Panama time, like the Reports pages; each number is compared with the previous period of the same length. Scope: `reports:read`. - [Get the team report](https://getricky.ai/en/docs/api/reference/reports/get-team-report.md): Assignments, messages, closes and medians per member and AI agent in the period. Days are America/Panama time, like the Reports pages. Scope: `reports:read`. - [Get the broadcasts report](https://getricky.ai/en/docs/api/reference/reports/get-broadcasts-report.md): WhatsApp broadcasts created in the period and their recipients' outcomes. Days and hours are America/Panama time, like the Reports pages; each number is compared with the previous period of the same length. Scope: `reports:read`. - [Get the ads report](https://getricky.ai/en/docs/api/reference/reports/get-ads-report.md): Meta ad spend and the conversations each ad brought in the period. Days and hours are America/Panama time, like the Reports pages; each number is compared with the previous period of the same length. Scope: `reports:read`. - **Ads** - [List Meta ad campaigns](https://getricky.ai/en/docs/api/reference/ads/list-meta-ads-campaigns.md): Campaigns of the connected Meta ad accounts, read live from Meta. Answers `rule_violation` when the organization has not connected Meta Ads, and `forbidden` when Meta no longer accepts its connection. Scope: `reports:read`. - [List Meta ad sets](https://getricky.ai/en/docs/api/reference/ads/list-meta-ads-ad-sets.md): Ad sets of the connected Meta ad accounts with budget and targeting, read live from Meta. Answers `rule_violation` when the organization has not connected Meta Ads, and `forbidden` when Meta no longer accepts its connection. Scope: `reports:read`. - [List Meta ads](https://getricky.ai/en/docs/api/reference/ads/list-meta-ads.md): Ads of the connected Meta ad accounts with their creative copy, read live from Meta. Answers `rule_violation` when the organization has not connected Meta Ads, and `forbidden` when Meta no longer accepts its connection. Scope: `reports:read`. - [Get Meta ads insights](https://getricky.ai/en/docs/api/reference/ads/get-meta-ads-insights.md): Spend, delivery and Meta's actions for the connected ad accounts over a period, per account, campaign, ad set or ad, computed live by Meta. Answers `rule_violation` when the organization has not connected Meta Ads, and `forbidden` when Meta no longer accepts its connection. Scope: `reports:read`. - **Agents** - [List agents](https://getricky.ai/en/docs/api/reference/agents/list-agents.md): Active agents, newest first. Archived agents are not listed. Scope: `agents:read`. - [Create an agent](https://getricky.ai/en/docs/api/reference/agents/create-agent.md): Creates an AI agent with its instructions, voice and capabilities. It answers no conversation until you assign it to one or make it a channel default in Ricky. Scope: `agents:write`. - [Get an agent](https://getricky.ai/en/docs/api/reference/agents/get-agent.md): One active agent with its full settings. Scope: `agents:read`. - [Update an agent](https://getricky.ai/en/docs/api/reference/agents/update-agent.md): Changes only the fields in the body. `capabilities` and `handoff_user_ids` replace their whole sets. Scope: `agents:write`. - [Archive an agent](https://getricky.ai/en/docs/api/reference/agents/archive-agent.md): Archives the agent and answers it as it was, with `archived_at`. Its conversations stop being answered by it and workflows that assign it are paused. Archiving twice answers `404`. Scope: `agents:write`. - [Get agent options](https://getricky.ai/en/docs/api/reference/agents/get-agent-options.md): The voices and capabilities an agent can be configured with. Scope: `agents:read`. - **Knowledge** - [List locations](https://getricky.ai/en/docs/api/reference/knowledge/list-knowledge-locations.md): Branches and places, newest first. Scope: `knowledge:read`. - [Create a location](https://getricky.ai/en/docs/api/reference/knowledge/create-knowledge-location.md): Adds a branch or place the agents can share. Scope: `knowledge:write`. - [Get a location](https://getricky.ai/en/docs/api/reference/knowledge/get-knowledge-location.md): One location; its `photo`, when it has one, carries a `download_url`. Scope: `knowledge:read`. - [Update a location](https://getricky.ai/en/docs/api/reference/knowledge/update-knowledge-location.md): Changes only the fields in the body. Scope: `knowledge:write`. - [Delete a location](https://getricky.ai/en/docs/api/reference/knowledge/delete-knowledge-location.md): Deletes it for good and answers it as it was. Scope: `knowledge:write`. - [Upload a location photo](https://getricky.ai/en/docs/api/reference/knowledge/create-knowledge-location-photo.md): Begins an upload in three steps: this call answers the location and an `upload_url`; `PUT` the bytes there; then call `POST /knowledge/locations/{location_id}/photo/complete`. A location has one photo: uploading another replaces it when the upload completes, and until then the current one stays. Scope: `knowledge:write`. - [Remove a location photo](https://getricky.ai/en/docs/api/reference/knowledge/delete-knowledge-location-photo.md): Removes the photo and any upload in progress, and answers the location. Copies already sent in conversations stay there. A location without a photo stays as it is. Scope: `knowledge:write`. - [Complete a photo upload](https://getricky.ai/en/docs/api/reference/knowledge/complete-knowledge-location-photo.md): Checks that the uploaded bytes are a JPEG or PNG of up to 5 MB, of the type they were sent with, and makes them the location photo. Send no body. Completing an upload that already finished changes nothing; with no upload in progress and no photo, `409 conflict`. Scope: `knowledge:write`. - [List directory contacts](https://getricky.ai/en/docs/api/reference/knowledge/list-knowledge-contacts.md): Contact cards of the knowledge directory, by display name. These are not CRM contacts. Scope: `knowledge:read`. - [Create a directory contact](https://getricky.ai/en/docs/api/reference/knowledge/create-knowledge-contact.md): Adds a contact card the agents can send to customers. Scope: `knowledge:write`. - [Get a directory contact](https://getricky.ai/en/docs/api/reference/knowledge/get-knowledge-contact.md): One contact card. Scope: `knowledge:read`. - [Update a directory contact](https://getricky.ai/en/docs/api/reference/knowledge/update-knowledge-contact.md): Changes only the fields in the body. Scope: `knowledge:write`. - [Delete a directory contact](https://getricky.ai/en/docs/api/reference/knowledge/delete-knowledge-contact.md): Deletes it for good and answers it as it was. Scope: `knowledge:write`. - [List files](https://getricky.ai/en/docs/api/reference/knowledge/list-knowledge-files.md): Documents and images the agents can consult or send, newest first. Scope: `knowledge:read`. - [Upload a file](https://getricky.ai/en/docs/api/reference/knowledge/create-knowledge-file.md): Begins an upload in three steps: this call answers the file, `uploading`, and an `upload_url`; `PUT` the bytes there; then call `POST /knowledge/files/{file_id}/complete`. Scope: `knowledge:write`. - [Complete an upload](https://getricky.ai/en/docs/api/reference/knowledge/complete-knowledge-file.md): Checks the uploaded bytes against the declared type and size, reads the content for the agents and answers the file, `ready`. Reading a long PDF can take minutes. Completing a `ready` file changes nothing. Scope: `knowledge:write`. - [Get a file](https://getricky.ai/en/docs/api/reference/knowledge/get-knowledge-file.md): One file; a `ready` one carries a `download_url`. Scope: `knowledge:read`. - [Update a file](https://getricky.ai/en/docs/api/reference/knowledge/update-knowledge-file.md): Changes its title, description or what the agents may do with it. Only a `ready` file changes; otherwise `409 conflict`. Scope: `knowledge:write`. - [Delete a file](https://getricky.ai/en/docs/api/reference/knowledge/delete-knowledge-file.md): Deletes it for good and answers it as it was. Copies already sent in conversations stay there. Scope: `knowledge:write`. - [Read what Ricky read](https://getricky.ai/en/docs/api/reference/knowledge/get-knowledge-file-reading.md): The full text Ricky read from a `ready` file, page by page for a PDF. Agents read this text to answer. A file not yet `ready` answers `409 conflict`. Scope: `knowledge:read`. - **Quick replies** - [List quick replies](https://getricky.ai/en/docs/api/reference/quick-replies/list-quick-replies.md): Every quick reply of the organization, by title. Scope: `quick_replies:read`. - [Create a quick reply](https://getricky.ai/en/docs/api/reference/quick-replies/create-quick-reply.md): Saves an answer operators can insert in the inbox. A title already in use, in any case, answers `409 conflict`. Scope: `quick_replies:write`. - [Get a quick reply](https://getricky.ai/en/docs/api/reference/quick-replies/get-quick-reply.md): One quick reply. Scope: `quick_replies:read`. - [Update a quick reply](https://getricky.ai/en/docs/api/reference/quick-replies/update-quick-reply.md): Changes only the fields in the body. A title already in use, in any case, answers `409 conflict`. Scope: `quick_replies:write`. - [Delete a quick reply](https://getricky.ai/en/docs/api/reference/quick-replies/delete-quick-reply.md): Deletes it and answers it as it was. It cannot be undone. Scope: `quick_replies:write`. - **Whats App** - [List templates](https://getricky.ai/en/docs/api/reference/whats-app/list-templates.md): WhatsApp templates of every connected business account, read live from Meta. Scope: `templates:read`. - [Create a template](https://getricky.ai/en/docs/api/reference/whats-app/create-template.md): Submits a template to Meta for review from the business account of `channel_id`. It answers the template as Meta has it, usually `PENDING`; follow it with `GET /templates/{template_id}`. A draft that breaks a rule answers `400` with the first problem; Meta refusing it answers `422 rule_violation` with its reason. Scope: `templates:write`. - [Get a template](https://getricky.ai/en/docs/api/reference/whats-app/get-template.md): One template, read live from Meta, with its review `status`: `PENDING` while Meta reviews it, then `APPROVED`, `REJECTED` or `PAUSED`. Read it again to follow Meta's review. Scope: `templates:read`. - [Edit a template](https://getricky.ai/en/docs/api/reference/whats-app/update-template.md): Changes the category or content of a template and sends it to Meta for review again. Meta allows it only for `APPROVED`, `REJECTED` and `PAUSED` templates, and limits how often an approved one can change; otherwise it answers `422 rule_violation`. An edit that keeps an image, video or document header sends `header` again with a new `handle`. Templates with buttons or components Ricky’s editor does not build cannot be edited here. Scope: `templates:write`. - [Delete a template](https://getricky.ai/en/docs/api/reference/whats-app/delete-template.md): Deletes the template at Meta. Meta deletes it in every language that shares its name, and the name cannot be used again for 30 days. Scope: `templates:write`. - [Validate a template draft](https://getricky.ai/en/docs/api/reference/whats-app/validate-template.md): Checks a draft with the rules of Ricky’s template editor and answers every problem found, without submitting anything to Meta. A body that is not a draft answers `400`; a draft that breaks a rule answers `200` with `valid: false`. Meta can still reject a valid draft in its review. Scope: `templates:read`. - [List WhatsApp numbers](https://getricky.ai/en/docs/api/reference/whats-app/list-whats-app-numbers.md): Every WhatsApp number of the organization, also disconnected ones, with its status, quality rating and messaging limit as Ricky last read them from Meta. Scope: `conversations:read`. - [Get a WhatsApp number](https://getricky.ai/en/docs/api/reference/whats-app/get-whats-app-number.md): One WhatsApp number by its channel ID. Scope: `conversations:read`. - [Update a WhatsApp number](https://getricky.ai/en/docs/api/reference/whats-app/update-whats-app-number.md): Turns calls to the number on or off at Meta. Ricky reads the number back from Meta and answers it as Meta confirms it. Scope: `conversations:write`. - [Upload a header sample](https://getricky.ai/en/docs/api/reference/whats-app/create-template-media-upload.md): An image, video or document header needs a sample file Meta reviews. Uploading it takes three steps: this call answers an `upload_url`; `PUT` the bytes there; then `POST /templates/media/complete` answers the `handle` for `header.handle`. Scope: `templates:write`. - [Complete a header sample](https://getricky.ai/en/docs/api/reference/whats-app/complete-template-media-upload.md): Checks the uploaded bytes against the type and size limits, sends them to Meta and answers Meta’s `handle`. Ricky deletes its copy either way, so a failed upload starts again with `POST /templates/media`. Scope: `templates:write`. - [Get the field mappings of a template](https://getricky.ai/en/docs/api/reference/whats-app/get-template-field-mappings.md): The template’s variables, read live from Meta, and the contact field that fills each one when Ricky sends the template to a contact, as in broadcasts. Scope: `templates:read`. - [Set the field mappings of a template](https://getricky.ai/en/docs/api/reference/whats-app/replace-template-field-mappings.md): Replaces every mapping of the template. Each one names a variable of `variables` and a contact field; a custom field must be the organization’s. Scope: `templates:write`. - [Edit a business profile](https://getricky.ai/en/docs/api/reference/whats-app/update-whats-app-business-profile.md): Changes the business profile customers see on the number at Meta, then answers the number with the profile Meta reads back. Scope: `conversations:write`. - [Upload a profile photo](https://getricky.ai/en/docs/api/reference/whats-app/create-profile-photo-upload.md): Begins a new profile photo in three steps: this call answers an `upload_url`; `PUT` the bytes there; then call `POST /whatsapp-numbers/{channel_id}/profile-photo/complete`. Scope: `conversations:write`. - [Complete a profile photo](https://getricky.ai/en/docs/api/reference/whats-app/complete-profile-photo-upload.md): Checks the uploaded photo, sets it on the number at Meta and answers the number. Ricky deletes its copy either way. Scope: `conversations:write`. - [Request a display name change](https://getricky.ai/en/docs/api/reference/whats-app/request-whats-app-display-name.md): Asks Meta to review a new display name for the number. The name changes only if Meta approves it; then `verified_name` and `name_status` change. Scope: `conversations:write`. - [Refresh a WhatsApp number](https://getricky.ai/en/docs/api/reference/whats-app/refresh-whats-app-number.md): Reads the number’s status, quality, limit, display name and business profile from Meta now, stores them and answers the number. Scope: `conversations:write`. - **Broadcasts** - [List broadcasts](https://getricky.ai/en/docs/api/reference/broadcasts/list-broadcasts.md): Newest first, with how many recipients are in each delivery status. Scope: `broadcasts:read`. - [Create a broadcast](https://getricky.ai/en/docs/api/reference/broadcasts/create-broadcast.md): Sends an approved WhatsApp template to an audience, now or at `scheduled_at`. Ricky fixes the recipient list now and sends through each number’s conversation, as a template sent from the inbox; variables the template maps to contact fields in Ricky are filled per contact. Answers `201` with the broadcast `queued` or `scheduled`; follow it with `GET /broadcasts/{broadcast_id}`. An audience without any WhatsApp number, or a number that is disconnected or lacks its Meta access, answers `422 rule_violation`. Scope: `broadcasts:write`. - [Get a broadcast](https://getricky.ai/en/docs/api/reference/broadcasts/get-broadcast.md): One broadcast with how many recipients are in each delivery status. Scope: `broadcasts:read`. - [Cancel a scheduled broadcast](https://getricky.ai/en/docs/api/reference/broadcasts/cancel-broadcast.md): Cancels a `scheduled` broadcast before it starts; nothing is sent. Once it is `queued` or sending, or already canceled, it answers `409 conflict`. Send no body. Scope: `broadcasts:write`. - [List broadcast recipients](https://getricky.ai/en/docs/api/reference/broadcasts/list-broadcast-recipients.md): Each number of the broadcast and where its message stands, in number order. Statuses change as WhatsApp reports them. Scope: `broadcasts:read`. - [Preview a broadcast audience](https://getricky.ai/en/docs/api/reference/broadcasts/preview-broadcast-audience.md): Counts the numbers an audience resolves to now, with the rules `POST /broadcasts` uses, without creating anything. The list can change before you create the broadcast. Scope: `broadcasts:read`. - **Webhook events** - [message.received](https://getricky.ai/en/docs/api/reference/webhook-events/message-received.md): A contact sent a message. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`. - [message.sent](https://getricky.ai/en/docs/api/reference/webhook-events/message-sent.md): The provider accepted a message from the organization. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`. - [message.delivered](https://getricky.ai/en/docs/api/reference/webhook-events/message-delivered.md): An outbound message reached the recipient device. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`. - [message.read](https://getricky.ai/en/docs/api/reference/webhook-events/message-read.md): The recipient read an outbound message. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`. - [message.failed](https://getricky.ai/en/docs/api/reference/webhook-events/message-failed.md): An outbound message failed for good; read the message for the reason. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`. - [conversation.opened](https://getricky.ai/en/docs/api/reference/webhook-events/conversation-opened.md): A conversation was created or reopened. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`. - [conversation.closed](https://getricky.ai/en/docs/api/reference/webhook-events/conversation-closed.md): A conversation was closed. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`. - [conversation.assignment_changed](https://getricky.ai/en/docs/api/reference/webhook-events/conversation-assignment-changed.md): A conversation was assigned, reassigned or unassigned. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`. - [conversation.agent_changed](https://getricky.ai/en/docs/api/reference/webhook-events/conversation-agent-changed.md): The AI agent answering a conversation changed: one was assigned, replaced or removed. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`. - [conversation.handoff_requested](https://getricky.ai/en/docs/api/reference/webhook-events/conversation-handoff-requested.md): An AI agent handed a conversation to a person. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`. - [conversation.handoff_resolved](https://getricky.ai/en/docs/api/reference/webhook-events/conversation-handoff-resolved.md): A person resolved a handoff: the conversation stays with a person or goes back to the AI agent. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`. - [contact.created](https://getricky.ai/en/docs/api/reference/webhook-events/contact-created.md): A contact was created, by a person, the API, an import or a first message. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`. - [contact.updated](https://getricky.ai/en/docs/api/reference/webhook-events/contact-updated.md): A contact's fields, tags or custom values were saved. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`. - [contact.tags_changed](https://getricky.ai/en/docs/api/reference/webhook-events/contact-tags-changed.md): A contact's tags changed. Every change in one save is one event; `contact.updated` fires too. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`. - [broadcast.completed](https://getricky.ai/en/docs/api/reference/webhook-events/broadcast-completed.md): A broadcast handed its last message to WhatsApp. Some recipients may still be waiting for WhatsApp to answer; read the broadcast for its counts. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`. - [broadcast.failed](https://getricky.ai/en/docs/api/reference/webhook-events/broadcast-failed.md): A broadcast finished and every recipient had failed; read its recipients for the reasons. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`. - [template.status_changed](https://getricky.ai/en/docs/api/reference/webhook-events/template-status-changed.md): Meta changed a WhatsApp template's status, for example approved, rejected or paused; read the template for it. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`. - [workflow.execution_failed](https://getricky.ai/en/docs/api/reference/webhook-events/workflow-execution-failed.md): A workflow execution failed for good; read the workflow executions for the error. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`. - [knowledge_file.ready](https://getricky.ai/en/docs/api/reference/webhook-events/knowledge-file-ready.md): A knowledge file finished uploading and Ricky read it. A file Ricky could not read is ready too, with `extraction_error`. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`. - [webhook.test](https://getricky.ai/en/docs/api/reference/webhook-events/webhook-test.md): Sent on demand by `POST /webhooks/{webhook_id}/test`; carries `webhook_id`. Ricky signs every delivery: `X-Ricky-Signature: v1=` is the HMAC-SHA256 of `.` keyed with the webhook `signing_secret`. After a secret rotation the header carries two comma-separated signatures, new first, until the previous secret expires: accept the event if any `v1=` value matches. Ricky sends it within seconds of the event. Answer any 2xx within 10 seconds; Ricky makes up to ten attempts with growing waits and may deliver an event twice, so deduplicate by `id`.