Start a script on a conversation

POST/api/v1/conversations/{id}/scriptsRead, no scope needed

Runs one of your scripts on a conversation from your own system, for example a pickup reminder after an order is packed.

A script sends real messages to a real customer. Only scripts you gave the API trigger when authoring them can be started here.

Request

curlshell

curl -X POST "https://icebot.icebergaisolutions.com/api/v1/conversations/6f1c2a90-3b7e-4d55-9a1e-2c8f0b7d4e11/scripts" \
  -H "Authorization: Bearer $ICEBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"script_id":"9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b"}'

Parameters

Name	In	Type	Description
`id` (required)	path	uuid	The conversation id.

Body

Field	Type	Description
`script_id` (required)	uuid	A script whose trigger is "API". Scripts with any other trigger are refused.

Example bodyjson

{
  "script_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b"
}

Responses

`200`

The script ran. messages is what the customer was sent, in order; outcome is waiting when it expects a reply, otherwise ended, handoff or ai.

200 responsejson

{
  "started": true,
  "messages": [
    "Hi Aisyah, your order #1042 is ready for pickup. Reply 1 to confirm a time."
  ],
  "outcome": "waiting"
}

Errors

Every endpoint can also return 401 (missing, unknown or revoked key), 403 (origin not allowed) and 429 (rate limited). See Errors.

Status	error	When
`400`	`script_id is required`	The body is not JSON or has no script_id.
`404`	`conversation not found`	The conversation is not this key's agent's.
`404`	`Script not found.`	No such script on this agent.
`409`	`(a sentence explaining why)`	The script is not API-triggered, or cannot start on this conversation now.

Source of truth: /api/v1/conversations/{id}/scripts in apps/dashboard/app/api/v1/conversations/[id]/scripts/route.ts.