SIP Integration

This guide explains how to integrate your Voice Agent with telephony systems using SIP to receive and make calls. The recommended approach is to connect the voice agent to a PBX extension for outbound trunking, or create a matching SIP outbound trunk for inbound trunking.

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

Connecting TO the SipPulse AI Inbound Trunk

You can create your own user on SipPulse AI in the Voice Agent Page:

SIP Configuration

• Destination URI: sip:sip.sippulse.ai
• Port: 5060
• Number: Add a number to the inbound trunk in E.164 format (e.g., +12025551234). This number needs to be unique and should be a number you own.
• Allowed IP Addresses: Add the source IP address of your PBX or phone system (Optional, e.g., 203.0.113.45)
• Allowed Source Numbers: Add the number in your SIP from header (Optional, e.g., +12025551234)
• Enable Authentication: Set to Yes (Highly recommended)
• Username: Create a unique username for this trunk (e.g., inbound_trunk_company)
• Password: Create a strong password for authentication (e.g., P@ssw0rd!2345)

Passing Agent Parameters to an Inbound Trunk

To pass parameters to the agent, such as variables, you can use the SIP header X-Additional-Instructions.

This header accepts variables in JSON format encoded in Base64.

Example:

Original JSON:

{
    "customer_name": "John Doe",
    "payment_amount": 5000
}

Base64 encoded value:

ewogICAgImN1c3RvbWVyX25hbWUiOiAiSm9obiBEb2UiLAogICAgInBheW1lbnRfYW1vdW50IjogNTAwMAp9

To send the data, use the SIP header:

X-Additional-Instructions: ewogICAgImN1c3RvbWVyX25hbWUiOiAiSm9obiBEb2UiLAogICAgInBheW1lbnRfYW1vdW50IjogNTAwMAp9

Configuring the Outbound Trunk

The easiest way to configure an outbound trunk is to connect it to an existing SIP extension if available on the Internet. Check with the maintainer of your PBX if it is possible to connect for outbound calls. We strongly advise disabling international calls on this extension to prevent fraud.

For the outbound trunk, you will need to create an extension on your telephone system and use these details to make calls through your SIP Trunk.

In the outbound trunk, you must specify the address of your SIP Trunk:

• Address: Your SIP Trunk address (e.g., sip:pbx.yourcompany.com:5060 or sip:203.0.113.45:5060)
• Number: The caller ID from where a call will be triggered (optional, e.g., +12025551234)
• Enable Authentication: Set to Yes
  • Username: Username for your PBX extension (e.g., sip_extension_101)
  • Password: Password for your PBX extension (e.g., ExtPwd!2345)

Example Configuration

Here's an example of a complete outbound trunk configuration:

Address: sip:pbx.acmecompany.com:5060
Number: +12025551234
Enable Authentication: Yes
Username: ext_101
Password: SecurePwd123!

Making Outbound Calls

Outbound calls can be executed in the playground or using the SipPulse API. You can pass parameters for the agent in the additional instructions.

The SIP outbound trunk is triggered by a RESTful API.

It uses the POST method with the endpoint:
https://api.sippulse.ai/bots/{id}/outbound-call

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

In the request body, use:

{
  "number": "+12025551234",
  "initial_text": "Hello, this is SipPulse AI calling to confirm your appointment tomorrow at 2 PM.",
  "additional_instructions": "{\"customer_name\":\"John Doe\",\"appointment_id\":\"AP-12345\"}",
  "activation_threshold": 3.5
}

Parameters:

• number: The phone number to call in E.164 format
• initial_text: The first message the agent will say when the call is answered
• additional_instructions: JSON string with variables for the agent
• activation_threshold: Confidence threshold for triggering the agent

For complete API documentation, visit: https://api.sippulse.ai/explorer/#/BotController/BotController.makeOutboundCall