Quickstart

This guide gets you up and running with Orbitali. You can configure your first agent using the Developer Dashboard (no-code track) or programmatically via the REST API (developer track).

Onboarding Track: Dashboard (No-Code)

If you want to quickly test the platform without writing backend code, follow the dashboard setup track.

1. Request Beta Access & Claim a Number

Navigate to the Orbitali dashboard at https://app.orbitali.ai.
Schedule a quick discovery session via the calendar page to request account activation.
Once active, go to Phone Numbers and click Claim Number to assign an available test number to your organization.

2. Create your Agent

Navigate to Agents and click Create Agent.
Give your agent a name (e.g., "Receptionist"), select a language (e.g., "en-US"), and choose an AI voice (e.g., "Aoede").
Choose Static Prompt and author your prompt in two parts:
- Identity: Who is the agent? (e.g., "You are Sofia, a warm and concise front desk receptionist at Acme Clinic.")
- Instructions: What does the agent do? (e.g., "Greet the caller, answer simple questions, and tell them we are open from 9 AM to 5 PM.")
Set a Static Greeting: The first message the agent speaks when answering (e.g., "Thanks for calling Acme Clinic. How can I help you today?").
Click Save Agent.

3. Assign your Phone Number

On your agent's configuration screen, navigate to the Phone Numbers section.
Select your claimed number from the dropdown list and click Assign.
Save the agent changes.

4. Make a Test Call

Dial the claimed phone number from your mobile phone.
The agent will answer instantly using the configured voice and static greeting.
Try speaking over the agent (barge-in) and ask about your business hours.

Onboarding Track: Public API (Developer)

If you are programmatically building integrations or deploying voice agents dynamically, use the REST API.

1. Generate an API Key

Go to the API Keys section in your dashboard settings and click Create API Key. Copy the key and store it securely; you will pass it as a Bearer token:

Authorization: Bearer <your_api_key>

2. Create an Agent via the API

Post to the /public/v1/agents endpoint. This creates an agent with static instructions. You can assign phone numbers during creation by providing their UUIDs in phoneNumberAssignments.

curl https://api.orbitali.ai/public/v1/agents \
  -X POST \
  -H "Authorization: Bearer $ORBITALI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Receptionist",
    "agentType": "webhook",
    "language": "en-US",
    "voiceName": "Aoede",
    "phoneNumberAssignments": [
      {
        "phoneNumberId": "40000000-0000-4000-8000-000000000001",
        "handoffPhoneNumber": "+15551234567"
      }
    ],
    "promptType": "static",
    "identity": "You are a helpful front-desk agent.",
    "instructions": "Keep answers short. Offer to take messages.",
    "greetingType": "static",
    "staticGreeting": "Hello! How can I help you today?"
  }'

The endpoint returns the created agent ID:

{
  "id": "9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9"
}

Agents created through the public API start as drafts. Activate the agent with PUT or PATCH /public/v1/agents/{agent_id} and status: "active" when it is ready to receive calls. Activation counts against your active-agent allowance; if the account is already at its limit, the API returns 409 with code: "AGENT_LIMIT_EXCEEDED" and a maxAgents value.

3. Register a Custom Webhook Tool

To allow your agent to fetch database info or trigger actions, configure a Server URL on the agent and register a tool. Orbitali will call your webhook whenever the model invokes this function.

Update Server URL: Ensure the agent has a serverUrl configured:

curl https://api.orbitali.ai/public/v1/agents/9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9 \
  -X PATCH \
  -H "Authorization: Bearer $ORBITALI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedUpdatedAt": "2026-06-24T12:00:00.000Z",
    "serverUrl": "https://api.yourdomain.com/orbitali/webhooks"
  }'

Register the Tool: Create a custom tool contract with a parameter validation schema (JSON Schema):

curl https://api.orbitali.ai/public/v1/agents/9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9/tools \
  -X POST \
  -H "Authorization: Bearer $ORBITALI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lookup_customer",
    "description": "Look up customer status and membership tier by phone number.",
    "parameterSchema": {
      "type": "object",
      "properties": {
        "phone": {
          "type": "string",
          "description": "E.164 caller phone number."
        }
      },
      "required": ["phone"]
    },
    "responseSchema": null,
    "timeoutMs": 5000,
    "onError": "return_error",
    "enabled": true,
    "toolUrl": null,
    "toolMethod": "POST",
    "toolHeaders": {}
  }'

4. Handle Webhook Events

Your backend webhook handler at https://api.yourdomain.com/orbitali/webhooks must accept POST requests and parse agent:tool-call events:

{
  "message": {
    "type": "agent:tool-call",
    "call": { "id": "call_123", "agentId": "agent_abc" },
    "toolCall": {
      "id": "call_xyz",
      "name": "lookup_customer",
      "arguments": { "phone": "+15559876543" }
    }
  }
}

Return a JSON payload containing the database result:

{
  "customerName": "Jane Doe",
  "membership": "Gold",
  "activeBookings": 1
}

Read the Webhooks Guide for instructions on verifying requests using x-orbitali-signature and handling dynamic prompts.