action.requires_approval, fired when a Your API endpoint is waiting for a person to approve it
One event tells you an approval is waiting. The envelope is described in the overview.
action.requires_approval
Fires when the agent wants to run a Your API endpoint marked requires approval. Nothing runs until someone approves it in the Inbox, and the visitor is told their request is being checked.
{
"actionId": 91,
"actionName": "issue_refund",
"actionDescription": "Refund an order",
"executionId": 4471,
"conversationId": 8214,
"chatbotId": 17,
"inputArgs": { "order_id": "1042", "amount": 39.0 },
"requestedAt": "2026-08-26T10:12:00.000Z"
}This payload is camelCase, while every other event is snake_case. That is a real inconsistency in the current API version, not a typo in these docs, so parse it as written. It will be aligned in a future api_version, and the version field on the envelope is how you will know.
inputArgs is exactly what the model wants to call the endpoint with, so an approver can see the actual order and amount rather than just the endpoint's name.
What to do with it
The approval itself happens in the Inbox; this event exists so it does not have to be noticed there. Typical uses:
- post it to the channel that owns that decision
- page whoever is on shift when
actionNameis one of the expensive ones - record every request for audit, approved or not