AI receptionist

An AI receptionist is a phone number whose calls are answered by one of your AI agents. Drop Cowboy® carries the call, runs the agent and records the result.

You build one from three pieces:

Steps

1. Build and publish the agent

Create the agent from an inbound template, attach your knowledge base, and publish it. See Start from a template and Attach to an agent. Keep the agent_id.

Lines use the agent's published version, so publish again after every change.

2. Get a number

List the numbers you already have:

curl https://api-v2.dropcowboy.com/phone/public/numbers \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"

Or rent one with POST /phone/public/numbers/rent. See Phone numbers. Renting answers 402 if the account has no funds or is past due: add funds and retry.

3. Create a phone line

To have the agent answer after hours while your team answers during the day, POST this to /phone/public/lines:

{
  "name": "Main line",
  "availability": {
    "tz": "America/Denver",
    "days": [
      { "open": false, "start": "9.0", "end": "17.0" },
      { "open": true,  "start": "9.0", "end": "17.0" },
      { "open": true,  "start": "9.0", "end": "17.0" },
      { "open": true,  "start": "9.0", "end": "17.0" },
      { "open": true,  "start": "9.0", "end": "17.0" },
      { "open": true,  "start": "9.0", "end": "17.0" },
      { "open": false, "start": "9.0", "end": "17.0" }
    ]
  },
  "rules": [
    { "start_rule": true, "end_rule": false, "action": "Queue", "action_data": {} },
    { "start_rule": false, "end_rule": true, "action": "Voicemail",
      "action_data": { "say": "Please leave a message." } }
  ],
  "after_hour_rules": [
    { "start_rule": true, "end_rule": false, "action": "AI Agent",
      "action_data": { "agent_id": "4c8e2a6f-3b9d-4e1a-9c7b-5d2f8a3e6b19" } },
    { "start_rule": false, "end_rule": true, "action": "Voicemail", "action_data": {} }
  ]
}

The response is the line. Its ivr_id is the line_id in the routes below.

A line has two rule lists:

• rules run during business hours.
• after_hour_rules run outside them.

Each list needs one step with start_rule: true, which runs when the call arrives. It also needs one with end_rule: true, which runs if the caller presses nothing. For a key-press menu, add steps with a user_input: the key the caller presses.

To have the agent answer around the clock, put the AI Agent step in both lists, or leave out availability.

Business hours

• availability.tz is the line's time zone, for example America/Denver.
• days has seven entries, Sunday first.
• start and end are hours in that time zone, as decimals: "9.5" is 9:30, "17.75" is 17:45. Leave them out for 0 and 24.
• A day with open: false is after hours all day.
• Without a tz, the line is never after hours, so only rules run.

Actions

Forward + Voicemail, Play, Sub-IVR and Trigger Automation are also available. Set them up in the dashboard, then read the line with GET /phone/public/lines/{line_id} to see the exact action_data to send.

4. Assign the number

curl -X POST https://api-v2.dropcowboy.com/phone/public/lines/$LINE_ID/assign \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "content-type: application/json" \
  -d '{ "number": "+13125550142" }'

Calls to that number now follow the line.

5. Test

Call the number from your own phone. If the line has business hours, call inside and outside them. Watch for the call results, or fetch the call with GET /phone/public/calls/{call_id} (see Call history).

Change the receptionist

POST /phone/public/lines/{line_id} updates a line. Send the whole rules or after_hour_rules array you want, because it replaces the existing one.

• To swap agents, change action_data.agent_id on the AI Agent step.
• To change what the agent says, edit and publish the agent. The line needs no change.
• To pause the agent, set it active: false. Replace the AI Agent step too if calls should go somewhere else in the meantime.

Results

ai_agent.call.started fires when a call reaches the agent. When the call ends, one more event fires: ai_agent.call.completed, ai_agent.call.failed, or an ai_agent.outcome.* event if the agent recorded an outcome such as transfer or opt_out. Receptionist calls carry direction: "inbound" and the line's ivr_id.

See Call results for the payload, and Webhooks to subscribe.

If calls never reach the agent

Check each of these:

• The agent has been published since your last change, and is active.
• The AI Agent step is in the list that applies at the time of the call (rules or after_hour_rules), with start_rule: true.
• availability.tz is set, and days starts on Sunday.
• The number is assigned to this line: check with GET /phone/public/numbers/{number}.
• The account has funds.

For other symptoms, see Troubleshooting.