SIP Integration

This guide explains how to integrate your Voice Agent with telephony systems using SIP to receive and make calls.

SipPulse AI allows SIP integration through its Proxy sip:sip.sippulse.ai:5060

---

Prerequisites

Before configuring SIP integration, make sure you have:

• A configured Voice Agent with LLM model and TTS voice defined
• Access to a telephony system (IP PBX, VoIP provider, or SIP trunk)
• Network permissions to connect to the SipPulse SIP server (port 5060 UDP/TCP)

Tip

The simplest way to get started is using the SIP URI method for inbound calls, which requires no additional configuration on your PBX beyond a call forwarding rule.

---

Accessing SIP Configuration

To configure your agent's SIP integration:

1. Navigate to Agents and select the desired agent
2. Access the Deploy tab through the navigation menu
3. Locate the SIP card and click Configure

---

Receiving Calls (Inbound)

There are two ways to configure your agent to receive calls: via direct SIP URI or through External SIP Registration.

Method 1: Via SIP URI (Recommended)

This is the simplest form of integration. SipPulse AI provides a unique SIP URI for each agent that can be used as a call destination.

How it works:

1. Enable "Inbound Calls" in the SIP configuration
2. Copy the agent's SIP URI (displayed automatically)
3. Configure your PBX to forward calls to this URI

The SIP URI follows the format:

{agent_id}@sip.sippulse.ai

Example PBX configuration:

• Configure call forwarding from an extension to the SIP URI
• Or create an outbound trunk pointing to the agent's SIP URI

Passing Parameters to the Agent

To pass contextual information to the agent during inbound calls, you can use custom SIP headers. All headers must be Base64 encoded.

Supported SIP Headers

Header	Behavior
X-Additional-Instructions	Concatenates text to the agent's instructions
X-Initial-Message	Replaces the agent's initial message
X-Uid	Sets a custom unique identifier for the session

X-Additional-Instructions

Passes contextual instructions that will be concatenated to the agent's existing instructions.

Example:

Original text:

The customer's name is John Smith and has an outstanding balance of $5,000.

Base64 encoded value:

VGhlIGN1c3RvbWVyJ3MgbmFtZSBpcyBKb2huIFNtaXRoIGFuZCBoYXMgYW4gb3V0c3RhbmRpbmcgYmFsYW5jZSBvZiAkNSwwMDAu

SIP header:

X-Additional-Instructions: VGhlIGN1c3RvbWVyJ3MgbmFtZSBpcyBKb2huIFNtaXRoIGFuZCBoYXMgYW4gb3V0c3RhbmRpbmcgYmFsYW5jZSBvZiAkNSwwMDAu

X-Initial-Message

Replaces the initial message configured in the agent with a personalized greeting.

Example:

Original text:

Hello John! Welcome to SipPulse, how can I help you?

SIP header:

X-Initial-Message: SGVsbG8gSm9obiEgV2VsY29tZSB0byBTaXBQdWxzZSwgaG93IGNhbiBJIGhlbHAgeW91Pw==

X-Uid

Sets a custom unique identifier for the session. Useful for:

• Linking the call to a ticket or case number in your system
• Integration with CRMs and customer service systems
• Easily finding the call record in history

Example:

Original text:

ticket-12345-john

SIP header:

X-Uid: dGlja2V0LTEyMzQ1LWpvaG4=

---

Method 2: External SIP Registration

Beta Feature

External SIP Registration is currently in beta and only available for selected organizations. If you don't see the "Enable External Registration" toggle in your SIP configuration, this feature is not yet enabled for your organization. Contact support@sippulse.com to request access.

External SIP Registration allows SipPulse AI to register as an extension on an external SIP server (your PBX, VoIP provider, etc.).

When to Use

Use External SIP Registration when:

• You have an existing SIP/VoIP provider and want to receive calls through it
• Your PBX doesn't support redirecting (call forwarding) to external URIs
• You want the agent to appear as an extension in your phone system
• You need bidirectional integration with a specific SIP trunk

Configuring External Registration

1. In the SIP configuration, enable Inbound Calls
2. Activate the Enable External Registration toggle
3. Fill in the fields:

Field	Description	Example
SIP Server	External SIP server address	sip.provider.com or sip.provider.com:5060
Username	Username for authentication	extension_100 or ai_agent
Password	Password for SIP server authentication	SecurePassword123!

4. Click Save to apply the settings

Credential Synchronization

If you've already configured an outbound trunk with the same provider, you can use the Sync from Outbound button to automatically copy the credentials.

Provider Requirements

Make sure your SIP provider allows external registrations and that the provided credentials have permission to receive calls. Some providers may require additional firewall configuration or IP whitelisting.

---

Making Calls (Outbound)

To make outbound calls through your agent, you need to configure an outbound SIP trunk.

Configuring the Outbound Trunk

The easiest way to configure an outbound trunk is to connect it to an existing SIP extension on your PBX. Check with your PBX administrator if it's possible to connect for outbound calls.

Warning

We strongly recommend disabling international calls on the extension used to prevent fraud.

In the SIP configuration, enable Outbound Calls and fill in:

Field	Description	Example
Address	Hostname or IP of your SIP trunk	pbx.yourcompany.com:5060
Phone Numbers	Numbers that can be used as caller ID	+15551234567
Username	Username for authentication (if required)	sip_extension_101
Password	Password for authentication	ExtPassword!2345

Complete configuration example:

Address: pbx.companyabc.com:5060
Numbers: +15551234567
Username: ext_101
Password: SecurePassword123!

---

Testing via Playground

After configuring the outbound trunk, you can test by making a call directly through the interface:

1. On the Deployments page, locate the SIP card
2. Click the phone button (or Make Call)
3. Enter the destination number in E.164 format (e.g., +15551234567)
4. Optionally, enable "Customize this call" to override settings
5. Click Start call

---

Via API

The outbound SIP trunk can be triggered via RESTful API:

POST https://api.sippulse.ai/agents/{id}/outbound-call

Where {id} is the unique identifier of your Voice Agent.

Request body:

{
  "number": "+15551234567",
  "metadata_overrides": {}
}

Parameters:

• number: The phone number to call in E.164 format
• metadata_overrides: JSON object with settings to override the agent's configuration

About Overrides

The metadata_overrides works as an override: you only need to include the fields you want to change. Fields not included or with empty values will use the agent's default configuration.

Complete metadata_overrides Example

{
    "phone_number": "+15551234567",
    "metadata_overrides": {
        "initial_message": "Hello! How can I help you today?",
        "additional_instructions": "customer_name: John",
        "variables": {},
        "inactivity_timeout": {
            "enabled": true,
            "time_in_seconds": 30,
            "message": "Due to inactivity, I will end our conversation now. Thank you very much and goodbye!",
            "presence_attempts": 0,
            "presence_message": "Are you still there?"
        },
        "max_duration": {
            "time_in_minutes": 60,
            "message": "Our conversation time has reached its limit. It was a pleasure helping you. Until next time!"
        },
        "ambient_sound": {
            "enabled": false,
            "audio": "ambient_1",
            "volume": 0.3
        },
        "thinking_sound": {
            "enabled": true,
            "audio": "thinking_1",
            "volume": 0.7
        },
        "tools": {
            "transfer_call": {
                "enabled": false
            }
        }
    }
}

Tip

An interesting hack to discover the correct metadata_overrides format is to use the browser console's Network tab and observe the payload sent by the Playground. This allows you to know exactly how to format the payload when calling the API.

For complete API documentation, visit: API Explorer

---

Phone Numbers (DIDs) - Advanced Feature

Limited Availability

This feature is only available for organizations with pre-registered DIDs. If you don't see the "Phone Number (DID)" section in the SIP configuration, contact support@sippulse.com to request DID activation for your organization.

What is a DID?

DIDs (Direct Inward Dialing) allow you to associate a specific phone number with your agent. When configured:

• Inbound calls: The system automatically identifies which agent should answer based on the dialed DID
• Outbound calls: The DID can be used as the caller ID

Configuring the DID

If your organization has available DIDs:

1. Open the agent's SIP Configuration
2. In the Phone Number (DID) section, select an available number
3. Click Save

Exclusive DIDs

Each DID can only be associated with one agent at a time. DIDs already in use by other agents appear disabled with an indication of which agent is using them. To switch a DID between agents, first remove it from the current agent.

---

Voice Tools for SIP Calls

SIP calls support specialized voice tools for advanced call handling that aren't available in other channels like Voice Playground or WhatsApp.

Available Tools

Tool	Description
End Dialog	Gracefully end calls when the conversation is complete
Transfer Call	Transfer calls to other SIP destinations (human agents, departments)
Send DTMF	Send DTMF tones to navigate external IVR menus
Receive DTMF	Collect DTMF input from callers (CPF, PIN codes, account numbers)

Configuration

Voice tools are configured in Agent Configuration > Call Configuration > Tools. Each tool can be individually enabled and customized with descriptions that guide the LLM on when and how to use them.

TIP

For detailed documentation on each voice tool including configuration options, LLM parameters, and best practices, see Voice Call Tools.

API Override Example

Control voice tools via metadata_overrides when making outbound calls:

{
  "phone_number": "+15551234567",
  "metadata_overrides": {
    "tools": {
      "receive_dtmf": {
        "enabled": true,
        "default_timeout": 20
      },
      "transfer_call": {
        "enabled": true,
        "destinations": [
          "sip:support@company.com",
          "sip:sales@company.com"
        ]
      },
      "end_dialog": {
        "enabled": true
      }
    }
  }
}

DTMF Collection Use Case

A common use case for SIP voice tools is collecting sensitive information via DTMF:

1. Agent prompts user: "Please enter your 11-digit CPF using the phone keypad"
2. User enters digits: Types CPF on their phone
3. Agent confirms: "I received 1-2-3-4-5-6-7-8-9-0-1. Is this correct?"
4. User confirms: "Yes"
5. Agent proceeds: Uses the confirmed CPF for the transaction

Testing Limitation

DTMF tools cannot be tested in Voice Playground. You must test with actual SIP calls to verify DTMF collection functionality.