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).

If you are using a coding agent such as Claude Code, Cursor, Windsurf, or Codex to configure Orbitali from your app repository, start with the MCP Server guide. The MCP server wraps the public API with agent-friendly tools for creating or reusing agents and registering only missing tool definitions.

Onboarding Track: Dashboard (No-Code)

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

1. Create your workspace

Navigate to https://app.orbitali.ai/signup and create an account.
Verify your email and name your organization once. If you were invited, join the existing organization.
Orbitali prepares your workspace automatically and opens the dashboard. Choose Create your first agent; you do not need a phone number to get started.

If preparation fails, use Try again to resume without creating another organization. Returning users go straight to their existing workspace.

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 profile (e.g., "eve").
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. Connect a Phone Number

When ready to take calls, open Numbers and connect an existing Telnyx or Twilio number.
Assign the number to your agent.
Save the agent changes.

4. Make a Test Call

Dial the connected 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",
    "aiIdentityDisclosureTemplateId": "named_agent",
    "voiceName": "eve",
    "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": {}
  }'

To replace or remove a tool later, call PUT or DELETE /public/v1/agents/{agent_id}/tools/{tool_id}. See the Agents API reference for the full request shape.

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.