Quickstart

There are two ways to get started with VoIPBin:

  • Try the Demo — Click the Try Demo Account button at admin.voipbin.net to explore VoIPBin instantly. No setup or sign-up needed.

  • Run the Sandbox — Run the full VoIPBin platform on your local machine using Docker. See the Sandbox section below.

For production use, you can sign up for your own account.

Sandbox

The VoIPBin Sandbox lets you run the entire VoIPBin platform on your local machine with a single command. No sign-up required — it comes with a pre-configured admin account and is ready to use immediately.

Prerequisites

  • Docker and Docker Compose v2

Install and Run

Clone the sandbox repository and launch the interactive CLI:

$ git clone https://github.com/voipbin/sandbox.git
$ cd sandbox
$ sudo ./voipbin

Initialize and start the services:

voipbin> init
voipbin> start

Once started, you can log in with the default admin account:

For full documentation, troubleshooting, and advanced usage, see the Sandbox GitHub repository.

Using Tutorials with the Sandbox

All tutorials in this documentation use https://api.voipbin.net as the API endpoint. If you are using the sandbox, substitute it with your local sandbox endpoint:

  • Production: https://api.voipbin.net

  • Sandbox: https://api.voipbin.test:8443

For example, to generate a token using the sandbox:

$ curl --request POST 'https://api.voipbin.test:8443/auth/login' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "username": "admin@localhost",
        "password": "admin@localhost"
    }'

Signup

To use the VoIPBin production API, you need your own account.

How to Sign Up

  1. Go to the admin console.

  2. Click Sign Up.

  3. Enter your email address and submit.

  4. Check your inbox for a verification email.

  5. Click the verification link in the email to verify your address.

  6. You will receive a welcome email with instructions to set your password.

Once your password is set, you can log in to the admin console and start making API requests.

Authentication

Every API request must be authenticated using either a Token (JWT) or an Accesskey. Both serve the same purpose — choose whichever fits your workflow.

Generate a Token

Send a login request with your username and password to receive a JWT token. The token is valid for 7 days.

$ curl --request POST 'https://api.voipbin.net/auth/login' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "username": "your-voipbin-username",
        "password": "your-voipbin-password"
    }'

Response:

{
    "username": "your-voipbin-username",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Use the token in subsequent requests via the Authorization header:

$ curl -k --request GET 'https://api.voipbin.net/v1.0/accesskeys' \
    --header 'Authorization: Bearer <your-token>'

Or as a query parameter:

$ curl -k --request GET 'https://api.voipbin.net/v1.0/accesskeys?token=<your-token>'

Generate an Accesskey

For long-lived authentication, generate an access key from the admin console. You can set a custom expiration when creating it.

_images/quickstart_authentication_accesskey.png

Use the access key as a query parameter:

$ curl -k --request GET 'https://api.voipbin.net/v1.0/accesskeys?accesskey=<your-accesskey>'

For more details, see the full Accesskey tutorial.

Call

Make an outbound voice call using the VoIPBin API. You can either define actions inline or reference an existing flow.

Make a call with inline actions

This example initiates a call and plays a text-to-speech message to the recipient:

$ curl --request POST 'https://api.voipbin.net/v1.0/calls?token=<your-token>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "source": {
            "type": "tel",
            "target": "<your-source-number>"
        },
        "destinations": [
            {
                "type": "tel",
                "target": "<your-destination-number>"
            }
        ],
        "actions": [
            {
                "type": "talk",
                "option": {
                    "text": "Hello. This is a VoIPBin test call. Thank you, bye.",
                    "language": "en-US"
                }
            }
        ]
    }'

The response includes the call details with "status": "dialing":

[
    {
        "id": "e2a65df2-4e50-4e37-8628-df07b3cec579",
        "flow_id": "6cbaa351-b112-452d-84c2-01488671013d",
        "source": {
            "type": "tel",
            "target": "<your-source-number>"
        },
        "destination": {
            "type": "tel",
            "target": "<your-destination-number>"
        },
        "status": "dialing",
        "direction": "outgoing",
        ...
    }
]

Make a call with an existing flow

If you have already created a flow, you can reference it by flow_id instead of defining actions inline:

$ curl --request POST 'https://api.voipbin.net/v1.0/calls?token=<your-token>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "source": {
            "type": "tel",
            "target": "<your-source-number>"
        },
        "destinations": [
            {
                "type": "tel",
                "target": "<your-destination-number>"
            }
        ],
        "flow_id": "<your-flow-id>"
    }'

For more details on flows, see the Flow tutorial.

Queue

Queues let you route incoming calls to available agents. Callers hear hold music or messages while waiting for an agent to become available.

Create a queue

This example creates a queue that routes calls randomly to agents matching a specific tag. While callers wait, they hear a text-to-speech greeting followed by a 1-second pause (looped):

$ curl --request POST 'https://api.voipbin.net/v1.0/queues?token=<your-token>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "name": "support queue",
        "detail": "Customer support queue",
        "routing_method": "random",
        "tag_ids": ["<your-tag-id>"],
        "wait_actions": [
            {
                "type": "talk",
                "option": {
                    "text": "Thank you for calling. Please wait while we connect you to an agent.",
                    "language": "en-US"
                }
            },
            {
                "type": "sleep",
                "option": {
                    "duration": 1000
                }
            }
        ],
        "timeout_wait": 100000,
        "timeout_service": 10000000
    }'

The response includes the created queue with its ID and configuration:

{
    "id": "99bf739a-932f-433c-b1bf-103d33d7e9bb",
    "name": "support queue",
    "detail": "Customer support queue",
    "routing_method": "random",
    "tag_ids": ["<your-tag-id>"],
    ...
}

Key parameters:

  • routing_method: How calls are distributed to agents (random, round-robin).

  • tag_ids: Agent tags to match. Only agents with matching tags will receive calls from this queue.

  • wait_actions: Actions executed while the caller waits (e.g., play messages, music).

  • timeout_wait: Maximum time (ms) a caller waits in the queue before timing out.

  • timeout_service: Maximum time (ms) for an active call with an agent.

For more details, see the Queue tutorial.

What’s Next

Now that you have made your first API calls, explore the full capabilities of VoIPBin:

  • Flow — Build programmable voice workflows with the visual flow builder.

  • AI — Integrate AI-powered voice agents with real-time speech processing.

  • Conference — Set up multi-party conferencing.

  • Conversation — Manage messaging conversations.

For the complete API reference, visit the API documentation.