Action requests

What RowCall posts to your action URL when the agent uses an action.

The agent uses an action

POSTaction.request → your URL

During a call, for an action taken by RowCall’s request (transport: rowcall): RowCall posts to your action URL and waits until deadline for your answer. A read is tried once more on a timeout or 5xx when time allows; the Idempotency-Key header (<callId>:<actionId>) is the same both times.

Headers

RowCall-Signaturestringrequired
t=<unix seconds>,v1=<hex>: HMAC-SHA256 of <t>.<raw body> with your signing secret. Check it, and that t is within 5 minutes, before trusting the body. During a secret rotation there are two v1 values.
Idempotency-Keystringrequired

What RowCall sends

actionIdstringrequired
Finish a pending action with it.
actionstringrequired
modestringrequired
One oflivetest
orgIdstringrequired
runIdstring or nullrequired
callIdstringrequired
contactobjectrequired
Show 1 fields insideHide the fields inside
- phonestring or nullrequired
argsmap of stringrequired
The action’s parameters, as the agent filled them.
metadatamap of stringrequired
The run’s metadata, as you started it.
isConfirmedbooleanrequired
Whether the shopper confirmed, for actions that need it.
deadlinestringrequired
Answer before this, or the action times out.

Your answer: 200

Done (ok: true, with any result the agent may use), or refused (ok: false).

Your answer: 202

Taking longer: finish it with POST /runs/{runId}/actions/{actionId}/result.

pendingbooleanrequired
One oftrue

Receive it

import { verifyActionRequest } from '@rowcall/sdk'
import express from 'express'

const app = express()

app.post('/rowcall/actions', express.raw({ type: 'application/json' }), (req, res) => {
  const body = req.body.toString()
  const isGenuine = verifyActionRequest({
    body,
    signature: req.get('RowCall-Signature') ?? '',
    secret: process.env.ROWCALL_SIGNING_SECRET,
  })
  if (!isGenuine) return res.sendStatus(401)
  const event = JSON.parse(body)
  // Do event.action with event.args, before event.deadline.
  res.status(200).json({ ok: true, result: { confirmed: true } })
})

Example

{
  "actionId": "act_q1w3e5r7t9y1u3i5o7p9",
  "action": "confirm_order",
  "mode": "live",
  "orgId": "org_t1y3u5i7o9p1a3s5d7f9",
  "runId": "run_8hq2x2m4q8w1z7p5n6b0",
  "callId": "cal_r4t6y8u0i2o4p6a8s0d2",
  "contact": {
    "phone": "+919812345678"
  },
  "args": {
    "order_id": "4821"
  },
  "metadata": {
    "shopify_order_id": "5523981"
  },
  "isConfirmed": true,
  "deadline": "2026-10-13T09:31:52.000Z"
}

Your answer

{
  "ok": true,
  "result": {
    "confirmed": true
  }
}