Ricky logorickyDocs

Create a workflow

POST
/workflows

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.

Authorization

bearerAuth
headerAuthorizationBearer <token>

An organization API key, rky_live_…, created in Settings → API. Send it only from a server.

Header Parameters

Idempotency-Key?string

Optional. A value you choose, unique per logical write, 8–200 characters: a UUID or an ID from your system such as order-10482-ready. Retrying with the same key and body replays the first response instead of repeating the write.

Length8 <= length <= 200

Request Body

application/json
  1. body

Creates a conversation workflow as a draft. Activating it is a separate call.

name*string

Display name.

Length1 <= length <= 80
definition*

Reacts to a conversation with messages, questions, waits and assignments.

Response Body

Success.

application/json
  1. response
data*

An automation Ricky runs for the organization.

curl -X POST 'https://getricky.ai/api/v1/workflows' \  -H 'Idempotency-Key: order-10482-ready' \  -H 'Content-Type: application/json' \  -d '{  "name": "Fuera de horario",  "definition": {    "trigger": "conversation_opened",    "channel_ids": [      "8f3c2a5e-6b1d-4c7a-9e2f-1a2b3c4d5e6f"    ],    "condition": {      "kind": "outside_business_hours",      "business_hours": {        "start": "09:00",        "end": "18:00",        "timezone": "America/Panama",        "weekdays": [          1,          2,          3,          4,          5        ]      }    },    "flow": {      "entry": "bienvenida",      "steps": [        {          "id": "bienvenida",          "kind": "send_message",          "text": "Hola, gracias por escribir a Casa Nativa. Abrimos de lunes a viernes de 9:00 a 18:00.",          "next": "motivo"        },        {          "id": "motivo",          "kind": "ask_question",          "text": "¿En qué te ayudamos?",          "answer_key": "motivo",          "choices": [            {              "id": "pedido",              "label": "Mi pedido",              "next": "asesor"            },            {              "id": "otro",              "label": "Otra consulta",              "next": "agente"            }          ],          "timeout_seconds": 3600,          "on_timeout": "agente",          "on_invalid": "agente",          "next": "agente"        },        {          "id": "asesor",          "kind": "assign_user",          "user_id": "2d4f6a8c-1b3d-4e5f-8a7b-9c0d1e2f3a4b",          "next": null        },        {          "id": "agente",          "kind": "assign_agent",          "agent_id": "7e8f9a0b-1c2d-4e3f-a4b5-c6d7e8f9a0b1",          "next": null        }      ]    }  }}'
{  "data": {    "id": "a3b4c5d6-e7f8-4a9b-8c0d-2e3f4a5b6c7d",    "name": "Fuera de horario",    "status": "active",    "type": "conversation",    "definition": {      "trigger": "conversation_opened",      "channel_ids": [        "8f3c2a5e-6b1d-4c7a-9e2f-1a2b3c4d5e6f"      ],      "condition": {        "kind": "outside_business_hours",        "business_hours": {          "start": "09:00",          "end": "18:00",          "timezone": "America/Panama",          "weekdays": [            1,            2,            3,            4,            5          ]        }      },      "flow": {        "entry": "bienvenida",        "steps": [          {            "id": "bienvenida",            "kind": "send_message",            "text": "Hola, gracias por escribir a Casa Nativa. Abrimos de lunes a viernes de 9:00 a 18:00.",            "next": "motivo"          },          {            "id": "motivo",            "kind": "ask_question",            "text": "¿En qué te ayudamos?",            "answer_key": "motivo",            "choices": [              {                "id": "pedido",                "label": "Mi pedido",                "next": "asesor"              },              {                "id": "otro",                "label": "Otra consulta",                "next": "agente"              }            ],            "timeout_seconds": 3600,            "on_timeout": "agente",            "on_invalid": "agente",            "next": "agente"          },          {            "id": "asesor",            "kind": "assign_user",            "user_id": "2d4f6a8c-1b3d-4e5f-8a7b-9c0d1e2f3a4b",            "next": null          },          {            "id": "agente",            "kind": "assign_agent",            "agent_id": "7e8f9a0b-1c2d-4e3f-a4b5-c6d7e8f9a0b1",            "next": null          }        ]      }    },    "updated_at": "2026-10-14T15:30:00.000Z"  }}