Extension & Softphone Setup

Create a SIP extension and register a softphone (Linphone) to receive calls from VoIPBIN. This is required for the Real-Time Voice Interaction scenario.

Prerequisites

A valid authentication token (String) or accesskey (String). See Authentication.
Your customer ID (UUID). Obtained from GET https://api.voipbin.net/v1.0/customer or from your admin console profile.
Linphone softphone installed on your computer or mobile device. Download from linphone.org.

Note

AI Implementation Hint

This section requires a human with a softphone to complete the registration and answer calls. AI agents can execute the API call to create the extension and instruct the human for the Linphone registration.

Create an extension

Create a SIP extension that your softphone will register to. The name (String, Required) identifies the extension for dialing. The detail (String, Required) is a description. The extension (String, Required) and password (String, Required) are used for SIP authentication.

$ curl --request POST 'https://api.voipbin.net/v1.0/extensions?token=<your-token>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "name": "quickstart-phone",
        "detail": "Quickstart softphone extension",
        "extension": "quickstart1",
        "password": "your-secure-password-here"
    }'

Response:

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "quickstart-phone",
    "detail": "Quickstart softphone extension",
    "extension": "quickstart1",
    "username": "quickstart1",
    "password": "your-secure-password-here",
    "domain_name": "550e8400-e29b-41d4-a716-446655440000",
    "direct_hash": "a8f3b2c1d4e5",
    "tm_create": "2026-02-21T10:00:00.000000Z",
    "tm_update": "",
    "tm_delete": ""
}

The id (UUID) is the extension’s unique identifier — use it for GET /extensions/{id}, PUT /extensions/{id}, or DELETE /extensions/{id} operations. For dialing, use the name field instead. Save the name (String) — you will use it as the call destination in the Real-Time Voice Interaction scenario.

Note

AI Implementation Hint

The extension and password are SIP credentials, not VoIPBIN login credentials. The name field is the extension identifier used when dialing (e.g., "target_name": "quickstart-phone" in the call request). The response includes both extension and username fields — they contain the same value (username is a Kamailio-internal mirror of extension). Choose a memorable extension value and a strong password.

Register Linphone

Configure your Linphone softphone to register with VoIPBIN using the extension credentials created above.

Linphone configuration:

Field	Value
Username	`quickstart1` (from the `extension` field above)
Password	The password you set when creating the extension
Domain	`<your-customer-id>.registrar.voipbin.net`
Transport	UDP

Replace <your-customer-id> with your customer ID (UUID) obtained from GET https://api.voipbin.net/v1.0/customer. For example, if your customer ID is 550e8400-e29b-41d4-a716-446655440000, the domain is 550e8400-e29b-41d4-a716-446655440000.registrar.voipbin.net.

Setup steps (Linphone desktop):

Open Linphone and go to Preferences > Account (or SIP Account on mobile).
Select I already have a SIP account (or Use SIP account).
Enter the username, password, and domain from the table above.
Save. Linphone should show Registered status within a few seconds.

If registration succeeds, the status indicator turns green. If it fails, see Troubleshooting below.

Troubleshooting

Extension creation returns 400 Bad Request:
- Cause: Missing required fields (name, detail, extension, password).
- Fix: Ensure all four fields are present in the request body.
Linphone shows “Registration failed” or “408 Timeout”:
- Cause: Incorrect domain, extension/username, or password. The domain must include your customer ID.
- Fix: Verify the domain is <your-customer-id>.registrar.voipbin.net. Double-check the extension and password match exactly what was set when creating the extension. Ensure UDP port 5060 is not blocked by your firewall.