Phone & SIP Setup

Overview

To use the voice assistant, you need a SIP-compatible phone number connected to Happ. This page covers the complete setup process.

For the full API reference, see api.happ.tools/reference.

Step 1: Get SIP Credentials

Contact one of the supported telephony providers to get:

• Phone number — Your SIP phone number
• SIP login — Authentication username
• SIP password — Authentication password
• Telephony URL — SIP server address

Step 2: Add Phone to Happ

Via Dashboard

1. Go to Phones in the sidebar
2. Click Add Phone
3. Fill in:
   • Phone Number — Your SIP phone number
   • SIP Login — Authentication username
   • SIP Password — Authentication password
   • Provider URL — SIP server address
   • Codec — A-law (default) or μ-law
   • Comment — Optional label for identification
4. Click Save

Via API

POST /api/phones
X-Access-Token: happ_your_token_here
Content-Type: application/json

{
  "phoneNumber": "+380501234567",
  "sipLogin": "your-sip-login",
  "password": "your-sip-password",
  "telephonyUrl": "sip.provider.com",
  "codec": "alaw",
  "comment": "Main office line"
}

Step 3: Link Phone to Assistant

Assign the phone number to an AI assistant:

Via Dashboard

1. In the phone settings, select an Assistant from the dropdown
2. Click Save

Via API

PATCH /api/phones/{phoneId}
X-Access-Token: happ_your_token_here
Content-Type: application/json

{
  "assistantId": "your-assistant-uuid"
}

A phone can be linked to only one assistant at a time. To change the assistant, update the assistantId.

Step 4: Add Telephony Provider Integration

1. Go to Integrations > Add Integration
2. Select your provider (Binotel, Ringostat, Phonet, or Unitalk)
3. Enter provider-specific credentials
4. Activate the integration

Step 5: Configure Voice Settings on Assistant

Go to your assistant's settings and configure:

• Voice — Choose from 30 built-in voices or ElevenLabs voices
• Audio format — Input and output audio format (default: PCM 8000)
• Eagerness — Response speed (Eager, Normal, Patient)
• Turn after silence — Seconds of silence before assistant speaks (default: 7)
• Soft timeout — Max wait for user response. -1 = unlimited

See Assistants > Voice Settings for details.

Step 6: Test

1. Call your connected phone number from any phone
2. You should hear the assistant's first message greeting
3. Speak naturally and verify the AI responds
4. Test any tools configured for the assistant

Managing Phones

Listing

GET /api/phones
X-Access-Token: happ_your_token_here

Updating

PATCH /api/phones/{phoneId}
X-Access-Token: happ_your_token_here
Content-Type: application/json

{
  "comment": "Updated label",
  "codec": "ulaw"
}

Deleting

DELETE /api/phones/{phoneId}
X-Access-Token: happ_your_token_here

Troubleshooting