Call received

`POST /telephony/callReceived`

Called when a call is received (inbound) or initiated (outbound).

For inbound calls (direction=in, default): creates a ticket, attempts customer identification from phone number, and returns the ticket ID. Routing happens later via getRouting.

For outbound calls (direction=out): creates a ticket, creates a queue entry (no routing needed), and links customer/contract data if available. Requires 'to'. No human initiator is required — the call can be fully autonomous/callflow-driven. If a human initiator is provided ('agentId'/'userId'), they are set to 'interacting' and the ticket is assigned to them. For bot/callflow-driven calls with no human on the line, omit 'agentId'/'userId' — presence is not touched and the queue is created as Unknown (out of routing).

Request body

routingenumbody

Determines how this call should be routed to an agent. Possible values are 'none', 'external', and 'native'.

none: Call is not routed, creates a new ticket in status closed, does not run AI agents.
external: Call should be routed, but routing engine is external. Enneo processes the ticket via its AI, and either connects to a specified agent (property 'userId' must be provided) or expects a later connection through a subsequent /agentConnected call.
native: Call should be routed using Enneo as the call routing engine. Returns a ticketId that can be polled to query agent availability. Options: none, external, native

contractIdstringbody

Optional contract id, if provided will be used for customer identification

customerIdstringbody

Optional customer id, if provided will be used for customer identification

phonestringbody

Phone number of the caller. Used for customer identification on inbound calls. For outbound calls, use 'to' instead.

tostringbody

Customer phone number being called. Required for outbound calls (direction=out). Used for customer identification.

agentIdintegerbody

ID of the agent initiating an outbound call where the human is on the line. Optional for outbound calls — if provided, the agent will be set to 'interacting' and assigned to the queue entry. Omit for bot/callflow-driven calls where no human is on the call.

aiAgentIdintegerbody

ID of the AI agent conducting the outbound call. When present with direction=out, the call is handled by a voicebot — no human agent is required, and any supplied human agent (userId/agentId) is recorded on the ticket but not set to interacting. Sufficient alone as the sole initiator for bot-only outbound calls. Ignored for inbound calls (direction=in).

transcriptobject[]body

Array of previous bot transcript entries

userIdintegerbody

Optional id of user that should be associated with the call. If that user has a browser window of enneo open, user will be redirected to the newly created ticket. Same effect as a subsequent /telephony/agentConnected API call. Requires property 'routing' to be set to 'external' or 'none'.

channelIdstringbody

Optional unique identifier of a third party system of this call. If provided, then it can be used as reference for any future updates to this call flow

callerNamestringbody

Optional name of the caller. Used for the fromName field of the ticket.

triggeredByintegerbody

ID of the user who triggered an autonomous/callflow-driven outbound call. Recorded in the ticketCreated event for attribution only — not put on the call (no presence/'interacting' change), not assigned to the ticket, not placed in the queue. Use 'agentId'/'userId' instead if the human is actually on the line.

directionenumbody

Direction of the call. Defaults to 'in' if not provided. Outbound calls (direction=out) require 'to'. A human initiator ('agentId'/'userId') is optional — omit for fully autonomous/callflow-driven calls. Options: in, out

subchannelIdintegerbody

Optional Enneo subchannel ID to associate with the ticket. Usually the ID of the call line as defined in the Enneo settings

externalTicketIdstringbody

Optional external ticket ID to associate with the ticket

statusenumbody

Status to set for the ticket. Defaults to 'closed' for routing 'none', 'open' for routing 'external' or 'native'. Options: open, closed, pending

triggerAiProcessingbooleanbody

Whether to trigger AI processing. Defaults to false for routing 'none', true for routing 'external' or 'native'.

Request Example

{
  "routing": "none",
  "contractId": "123456",
  "customerId": "789012",
  "phone": "+491234567890",
  "to": "+491234567890",
  "agentId": 1,
  "aiAgentId": 456,
  "transcript": [
    {
      "speaker": "agent",
      "message": "Hello, my name is AI Assistant. How can I help you today?",
      "timestamp": "2024-01-23T14:32:11Z"
    }
  ],
  "userId": 42,
  "channelId": "call_123abc456",
  "callerName": "John Smith",
  "triggeredBy": 1,
  "direction": "in",
  "subchannelId": 5,
  "externalTicketId": "ext-123",
  "status": "open",
  "triggerAiProcessing": true
}

Responses

200 — Successful operation

Response Example

{
  "success": true,
  "ticketId": 2142,
  "contractId": null,
  "customerId": null,
  "ioResponse": "None, as routing is not external",
  "queueId": 123
}

400 — Invalid input

500 — Internal error