KilevelDocs
Platform

API reference

Outbound Triggers

2 endpoints. Add your API key in the authentication panel to send test requests from this page.

Trigger an outbound call

POST/api/external/v1/outbound/calls

Directly triggers an outbound call to a destination phone number. This is the lightweight API for starting one-off outbound call sessions without creating a full CSV/JSON call job.

Select the flow with exactly one of:

  • flowId / flowApiId: reference a flow you've built and saved in the dashboard. flowId accepts either the internal UUID or the flow API ID; flowApiId is the explicit alias. If all three (flowId, flowApiId, flow) are omitted, Kilevel falls back to your default manual-call flow.
  • flow: an inline/transient flow definition for one-off calls that don't need a reusable, dashboard- managed flow — nothing is written to your flow library. See the flow field description for the full supported shape and which fields are ignored.

rowData becomes the call's contact/row payload, while contextData preloads session memory. If you configured flow-session webhooks globally or on the selected flow, those webhooks will also run for the resulting outbound call session (not applicable when using an inline flow).

Request body application/json

  • flowIdstring

    Optional flow reference. Accepts either the internal UUID or a flow API ID. If omitted (and `flow` is also omitted), Kilevel uses your default manual-call flow. Provide at most one of flowId, flowApiId, or flow.

  • flowApiIdstring

    Optional explicit flow API ID. Preferred for external integrations. Provide at most one of flowId, flowApiId, or flow.

  • flowFlow

    Optional inline/transient flow definition — an alternative to flowId/flowApiId for one-off calls/chats that don't need a reusable, dashboard-managed flow. Nothing is written to your flow library; the definition is stored only for the lifetime of this call/chat session (and its thread, for follow-up messages), not TTL'd or auto-deleted otherwise. Provide at most one of flowId, flowApiId, or flow. Accepts almost the same shape as a flow exported from the dashboard — master prompt, messages, voice/language/timing settings, tools, variables, structured outputs, pronunciation dictionaries, knowledge base, session states, and event-trigger tool refs all work. The following fields are ignored if present, since they don't apply to a one-shot/session-scoped definition: id, apiId, userId, archived, createdAt, updatedAt, projectId, iconKey, iconColor, mermaid* (diagram state), apiConfig (session webhooks — not applicable, this flow is never reused outside its own call/thread), isTemplate, templatePublished, templatePublicationLabel, templatePublicTitle, templateDescription, templateIcon, templateImageUrl, referenceFlowId, bornFromTemplate, templateOverrideState, templateDetachMode, templateDetachSourceFlowId, templateParameterScopeEnabled, supportedLanguages, and the defaultTestCall/Chat* preset fields.

  • customerNumberstring

    Required target phone number in E.164 format

  • fromPhoneNumberstring

    Optional fixed caller ID / sending phone number in E.164 format

  • allowedPhoneNumbersarray of string

    Optional allowlist of caller IDs to use for this row

  • contactNamestring

    Optional contact name mirrored into rowData.name and rowData.fullName

  • contactEmailstring

    Optional contact email mirrored into rowData.email

  • rowDataobject

    Optional row payload made available to the flow as rowData

  • contextDataobject

    Optional session memory preloaded before the call starts. Accessible later as contextData.* / sessionMemory.*

  • languagestring

    Optional language override for this call

  • voiceIdstring

    Optional voice ID override for this call

  • firstMessageModestring

    Optional first-message mode override for this call

Responses

  • 200Outbound call was queued
  • 401Missing or invalid API key
  • 403Key is valid but lacks access to this resource
  • 404Requested resource not found

Trigger an outbound chat

POST/api/external/v1/outbound/chats

Directly triggers an outbound interactive chat session with a contact. Supported channels:

  • CHAT: creates an API-managed chat session that can be fetched via the chat-session endpoints.
  • SMS: sends the opening assistant message over your configured SMS delivery channel.
  • WHATSAPP: sends the opening assistant message over your configured WhatsApp delivery channel.

contextData is stored as session memory before the outbound chat starts. If you configured flow-session webhooks globally or on the selected flow, those webhooks will also run for the resulting outbound chat session (not applicable when using an inline flow).

Request body application/json

  • flowIdstring

    Flow reference. Accepts either the internal UUID or a flow API ID. Provide exactly one of flowId, flowApiId, or flow.

  • flowApiIdstring

    Optional explicit flow API ID. Preferred for external integrations. Provide exactly one of flowId, flowApiId, or flow.

  • flowFlow

    Optional inline/transient flow definition — an alternative to flowId/flowApiId for one-off calls/chats that don't need a reusable, dashboard-managed flow. Nothing is written to your flow library; the definition is stored only for the lifetime of this call/chat session (and its thread, for follow-up messages), not TTL'd or auto-deleted otherwise. Provide at most one of flowId, flowApiId, or flow. Accepts almost the same shape as a flow exported from the dashboard — master prompt, messages, voice/language/timing settings, tools, variables, structured outputs, pronunciation dictionaries, knowledge base, session states, and event-trigger tool refs all work. The following fields are ignored if present, since they don't apply to a one-shot/session-scoped definition: id, apiId, userId, archived, createdAt, updatedAt, projectId, iconKey, iconColor, mermaid* (diagram state), apiConfig (session webhooks — not applicable, this flow is never reused outside its own call/thread), isTemplate, templatePublished, templatePublicationLabel, templatePublicTitle, templateDescription, templateIcon, templateImageUrl, referenceFlowId, bornFromTemplate, templateOverrideState, templateDetachMode, templateDetachSourceFlowId, templateParameterScopeEnabled, supportedLanguages, and the defaultTestCall/Chat* preset fields.

  • channelstring

    Channel to start: CHAT, SMS, or WHATSAPP

  • assistantPhoneNumberstring

    Required for SMS/WHATSAPP. Your sending phone number in E.164 format.

  • contactIdentifierstring

    Optional external contact/session identifier. Used primarily for CHAT sessions.

  • contactNamestring

    Optional contact name

  • contactEmailstring

    Optional contact email

  • contactPhonestring

    Required for SMS/WHATSAPP. Optional for CHAT.

  • contextDataobject

    Optional session memory preloaded before the outbound chat starts. Accessible as contextData.* / sessionMemory.*

  • initialMessagestring

    Optional explicit opening assistant message. If omitted, the flow's normal initial assistant message logic is used.

Responses

  • 200Outbound chat session created
  • 401Missing or invalid API key
  • 403Key is valid but lacks access to this resource
  • 404Requested resource not found