Call flow

Nodes

Each node has an id, a type, a position on the canvas (x, y) and its data. Node ids are kept when an agent is duplicated, so a script can change the same node in every copy.

Edges and conditions

Edges link two nodes (source, target). An edge can carry a condition, which decides the path the call takes:

A minimal call flow

{
  "nodes": [
    {
      "id": "start", "type": "startCall", "position": { "x": 0, "y": 0 },
      "data": {
        "brief": "<p>You are Alice, the receptionist of Club Lyon Part-Dieu. Answer briefly and warmly.</p>",
        "welcomeMessage": "Hello, this is Alice, the AI assistant of Club Lyon Part-Dieu. How can I help?"
      }
    },
    {
      "id": "hours", "type": "knowHow", "position": { "x": 0, "y": 160 },
      "data": { "title": "Opening hours", "prompt": "<p>The club is open every day from 6am to 11pm.</p>" }
    },
    {
      "id": "end", "type": "endCall", "position": { "x": 0, "y": 320 },
      "data": { "endCallMessage": "Thank you for calling. Have a good day!" }
    }
  ],
  "edges": [
    { "id": "e1", "source": "start", "target": "hours" },
    { "id": "e2", "source": "hours", "target": "end" }
  ]
}

The prompt the model reads is the brief followed by the nodes in diagram order. Prompts are HTML: keep the tags when you write one back.

Outbound settings

The outbound object of startCall applies to the calls a campaign places.

Transfers

A forwardCall node runs when its prompt applies: the agent says the forwardingMessage and transfers the caller to the node's destination.

The transfer settings are the same for both:

Look up the number during the call

When the right number depends on the caller (the subcontractor of their area, the agency of their postcode, the technician on call this week), set destinationType to lookup: your service picks the number while the caller waits. The number never passes through the model, so it cannot be misheard or made up, and hundreds of numbers stay out of the prompt.

{
  "id": "technician", "type": "forwardCall", "position": { "x": 320, "y": 160 },
  "data": {
    "title": "Transfer to technician",
    "prompt": "<p>Once the caller has given their address, transfer them.</p>",
    "forwardingMessage": "I'm putting you through to the technician of your area.",
    "destinationType": "lookup",
    "lookupUrl": "https://example.com/api/transfer-number?token=YOUR_SECRET",
    "lookupMessage": "One moment, I'm finding the technician of your area.",
    "lookupParameters": {
      "type": "object",
      "properties": {
        "address": { "type": "string", "description": "The caller's full address" }
      },
      "required": ["address"]
    },
    "transferMode": "cold",
    "fallbackMessage": "The technician cannot be reached. I'll take a message."
  }
}

1. The node becomes a tool of the agent, named after the camelCase form of its title (Transfer to technician becomes transferToTechnician). Its prompt tells the agent when to call it, and lookupParameters, a JSON Schema in the format of a custom tool's parameters, lists what the agent collects first. Without it, the agent sends no arguments.
2. The agent says the lookupMessage (by default One moment please. in the agent's language), and CallShift posts to lookupUrl the same request as to a custom tool: the tool's name in name, the arguments in args, the call so far in call and, when the caller is a known contact, the contact.
3. Your service answers with the number, or with the reason there is none.
4. With a number, the agent says the forwardingMessage and transfers the caller, cold or warm, with the node's settings.

Your service's answer

A match gives the number:

{
  "number": "+33612345678",
  "message": "I'm putting you through to Dupont Plumbing, the technician of your area.",
  "context": "Subcontractor for Lyon 3rd, contract 4521"
}

No match gives the reason, with any HTTP status:

{
  "error": "Address outside our service area",
  "context": "We cover Lyon and its suburbs only"
}

Answer within 5 seconds. Past that, and for a body with neither number nor error, an error status without an error, a number that is not valid or is in another country, or a call from a browser, which is on no line, there is no transfer either: the agent is told it is not possible, and the reason is in the dashboard's tool logs. A number abroad is refused so that a service that is wrong, or compromised, cannot send your calls to another country.

The request carries no signature: put a secret token in the URL and check it.