Skip to main content

Creating Calls

HuskyVoice AI allows you to initiate voice conversations programmatically. You can trigger calls using either our REST API for custom applications or Inbound Webhooks for no-code tools.

Before You Begin​

Make sure you have completed these three steps before initiating a call. If any of these are missing, your call will not go through.

Step 1 — Create an Outbound Agent​

An Agent is your AI voice assistant — it handles the conversation on your behalf. You need at least one Outbound Agent set up in your HuskyVoice dashboard before making any calls.

Go to Dashboard → Agents → Create Agent and select Outbound as the type.

Step 2 — Assign a Phone Number to the Agent​

Your agent needs a phone number to call from. Without an assigned number, calls cannot be placed.

Go to Dashboard → Agents → Select your Agent → Phone Numbers → Assign Number.

Step 3 — Generate an API Key​

An API Key is a unique password that lets your application talk to HuskyVoice securely. You need this to authenticate your requests.

Go to Dashboard → Integrations → API Keys → Generate New Key. Copy and store it safely — it will not be shown again.

Not a developer?

If you are using a no-code tool like Zapier or HubSpot, you only need Steps 1 and 2. Use the Inbound Webhook tab below instead of the REST API.

1. Using the REST API​

Best for developers building custom applications. Authenticate using your API Key.

curl -s -X POST https://api.huskyvoice.ai/v1/calls \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_123",
    "user_number": "+91XXXXXXXXXX",
    "user_name": "John Doe",
    "user_email": "john.doe@example.com",
    "scheduled_time": "2026-07-15T18:30:00Z",
    "additional_info": {
      "purpose": "Appointment Confirmation"
    }
  }'

Sample Response:

{
  "data": {
    "call_id": "call_abc123",
    "scheduled_at": "2024-01-27T03:02:00.000Z",
    "status": "queued"
  }
}

What Happens Next?​

Once your call is initiated, HuskyVoice queues it and connects the agent to the contact. You can track the live status and outcome of the call via Call Status.

tip

Save the call_id from the response — you'll need it to fetch status updates or cancel the call later.

Technical Details​

FieldRequiredDescription
agent_idYesThe unique ID of the AI agent to use for this call.
user_numberYesThe target phone number with country code (e.g., +91XXXXXXXXXX).
user_nameNoThe user's name.
user_emailNoThe user's email address.
additional_infoNoA JSON object containing variables your agent can reference during the call.
scheduled_timeNoISO 8601 timestamp for when the call should be placed. Must include an explicit UTC offset and be in the future. Defaults to immediate (~15 seconds after the request) if omitted.
Legacy field names

contact_number, contact_name, and contact_email are still accepted as aliases for user_number, user_name, and user_email for backward compatibility — new integrations should use the user_* names. Don't send both names for the same field in one request.

Scheduling a call for later

Use scheduled_time to queue a call for a specific future time instead of immediately — for example, a reminder call an hour before an appointment. The call will be placed at that time rather than right away.

Always include an explicit UTC offset

scheduled_time must end in Z (UTC) or an explicit offset like +05:30 — for example 2026-07-15T18:30:00Z or 2026-07-15T18:30:00+05:30. Bare timestamps with no offset (e.g. 2026-07-15T18:30:00) are rejected with a 400 error, because they would otherwise be interpreted using the server's local timezone rather than yours — the same string could resolve to a different actual call time depending on which server processes it. Always specify the offset explicitly to avoid this ambiguity.

Using additional_info in Your Agent Prompt​

The fields you pass in additional_info can be used directly inside your agent's prompt using double curly braces {{ }}. This lets your agent personalise the conversation for each contact.

Example — passing additional info in the API call:

{
  "agent_id": "agent_123",
  "user_number": "+91XXXXXXXXXX",
  "user_name": "John Doe",
  "user_email": "john.doe@example.com",
  "additional_info": {
    "purpose": "Appointment Confirmation"
  }
}

Example — referencing them inside your agent prompt:

Hi, this call is regarding: {{purpose}}. Please confirm if you will be attending.

What the agent will say:

"Hi, this call is regarding: Appointment Confirmation. Please confirm if you will be attending."

tip

You can pass up to 25 key-value pairs in additional_info. Use clear, descriptive key names so your agent prompt stays readable.