Graine AI
API referenceCalls

Send an event to a live call

Send a named event into a live call, from your own server.

Send a named event into a live call, from your own server.

Use it when something happens outside the call that the agent should react to at once: the customer opened a payment link, a payment went through, a form was submitted. On a flow agent, the step the call is on takes its path that waits for this event, and the next step speaks without waiting for the caller. The event's data becomes fields of the call, which the flow's rules can read and its steps can use as {names}, whether or not a path waits for the event. A step with no path for this event stays where it is.

202, not 200. The event is queued and reaches the call in about a second. If the agent is speaking, or the caller is, it is handled when that turn ends; several events are handled in the order they were sent.

404 means no such call in your organization. 409 means the call is not live: it is scheduled and has not been placed yet, it has already ended, or it has been placed but is still connecting (that answer carries Retry-After).

Rate limit: 2000 requests per minute per organization, counted together with every endpoint that has no stricter limit of its own. Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.

POST
/v2/calls/{execution_id}/events
/v2/calls/dbcffa37-92a1-4ae7-9814-71ca7b8ab3d3/events

The Authorization access token

Authorization

Authorization
Required
Bearer <token>

Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.

In: header

Request Body

application/jsonRequired

nameName | null

The event's name (required, as name or event). On a flow agent, a path that waits for this event (when.type event, when.event this name) on the step the call is on is taken at once.

Maximum length: 64

eventEvent | null

The same as name, for clients that send event and properties.

Maximum length: 64

dataData | null

Fields the event carries, up to 8 KB as JSON. They become fields of the call: the flow's rules can read them and its steps can use them as {names}, whether or not a path waits for the event.

propertiesProperties | null

The same as data, for clients that send event and properties.

Path Parameters

execution_id
Required
Execution Id

The call's id, as returned by POST /v2/calls or GET /v2/calls.

Query Parameters

organization_idOrganization Id

Optional. Must equal your key's organization.

Response Body

202

Successful Response

acceptedAccepted

Always true: the event is queued and reaches the call in about a second.

Default: true

name
Required
Name

The event's name, as sent.

execution_id
Required
Execution Id

The call it was sent to.

statusStatus

Always accepted.

Default: "accepted"

event
Required
Event

The same as name.

run_id
Required
Run Id

The same as execution_id.

401

1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented instead of an API key.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

403

1102 — the key is valid but lacks the scope this endpoint requires, or names another organization. GET /v2/scopes reports what a key holds.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

404

1200 — no such resource in your organization. A resource belonging to another organization answers 404, never 403.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

409

1201 — the resource's current state does not allow this action.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

422

1001 — the body or query failed validation; the message names the first offending field.

error
Required
integer

Stable integer code from the error table. Branch on this, not on the message.

message
Required
string

One human-readable sentence. Wording may change; the code will not.

429

1300 — the per-organization request rate or concurrent-call limit was reached. Carries Retry-After.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

503

1501 — a service this endpoint depends on is unreachable or returned a 5xx.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

curl -X POST "https://api.graine.ai/v2/calls/dbcffa37-92a1-4ae7-9814-71ca7b8ab3d3/events?organization_id=string" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "payment_completed",
    "event": "payment_completed",
    "data": {
      "amount": 2499,
      "method": "upi"
    },
    "properties": {
      "amount": 2499,
      "method": "upi"
    }
  }'

Successful Response

{
  "accepted": true,
  "name": "payment_completed",
  "execution_id": "dbcffa37-92a1-4ae7-9814-71ca7b8ab3d3",
  "status": "accepted",
  "event": "payment_completed",
  "run_id": "dbcffa37-92a1-4ae7-9814-71ca7b8ab3d3"
}

Previous

List executions GET

Next

Stop or cancel a call POST