AI Receptionist

A hosted AI receptionist is a phone number whose calls are answered by one of your AI agents. DropCowboy carries the call, runs the agent and records the result. There is no widget and nothing to host.

You build one from three pieces:

Line and number routes need numbers:read / numbers:write. Agent routes need agents:read / agents:write.

If you also want a "talk to us" button on your website, that is the receptionist Building Block, which uses the same agent.

Steps

1. Build and publish the agent

Create it from an inbound template, attach your knowledge base, and publish. See AI agents and knowledge bases. 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. Renting answers 402 (payment-required) if the account has no funds or is past due.

3. Create a phone line

A line has two rule lists:

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

availability sets the hours. Each list needs one step with start_rule: true (what happens when the call arrives) and one with end_rule: true (what happens if the caller presses nothing).

To have the agent answer after hours while your team answers during the day:

{
  "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": {} }
  ]
}

POST it to /phone/public/lines. The response carries the line's ivr_id, which is the line_id in the routes below.

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

Business hours

• days has seven entries, Sunday first.
• start and end are hours in the line's time zone, as decimals: "9.5" is 9:30, "17.75" is 17:45.
• 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 also exist. Their settings are easiest to set up in the dashboard; read the line back with GET /phone/public/lines/{line_id} to see the exact action_data to send.

For a key-press menu, give extra steps a user_input (the key the caller presses) alongside the start and end steps.

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, inside and outside business hours if the line has both. Watch for the webhook events below, or fetch the call with GET /phone/public/calls/{call_id}.

Change the receptionist

POST /phone/public/lines/{line_id} updates a line (this route uses POST, not PUT). Send the whole rules or after_hour_rules array you want: 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 if calls should go somewhere else meanwhile.

Results

Every answered call fires one webhook: ai_agent.call.completed, or an ai_agent.outcome.* event if the agent recorded an outcome such as transfer or opt_out. Inbound calls have direction: "inbound" and the line's ivr_id. See AI agents for the payload and webhooks to subscribe.

Checklist when calls are not reaching the agent

• 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: GET /phone/public/numbers/{number}.
• The account has funds.