Search Results for

    Show / Hide Table of Contents

    SIP Connector

    Session Initiation Protocol (SIP) is a text-based signaling protocol used to manage media sessions between two IP-connected endpoints. It's the primary signaling protocol used by VoIP systems when establishing calls. LiveSwitch supports SIP configuration to connect telephone devices to the Media Server.

    Note

    LiveSwitch doesn't support making video calls with the SIP Connector.

    You can configure SIP for your LiveSwitch application to accept inbound calls or make outbound calls.

    Requirements

    You need to set up a SIP trunk account with a third-party SIP provider or host your own SIP trunk server with the following requirements:

    • If you want your app to support outbound calling, the SIP trunk must support receiving delayed offers. The following describes the outbound call workflow:
      1. LiveSwitch SIP Connector sends an empty INVITE to the SIP trunk.
      2. LiveSwitch SIP Connector receives an ACK with an SDP offer to the SIP trunk.
      3. LiveSwitch SIP Connector sends an OK with an SDP answer to the SIP trunk.
    • If you want your app to support inbound calling, the SIP trunk must support sending early offers. The following describes the inbound call workflow:
      1. LiveSwitch SIP Connector receives an INVITE with an SDP offer to the SIP trunk.
      2. LiveSwitch SIP Connector sends an ACK with an SDP answer to the SIP trunk.
      3. LiveSwitch SIP Connector receives an empty OK to the SIP trunk.

    Trunk Configuration

    Configure your SIP trunk so that your LiveSwitch application can support making inbound or outbound calls.

    1. In the LiveSwitch Console > Deployments > SIP Configuration section, click NEW to add a new trunk.

    2. Enter your SIP trunk's domain name.

    3. Select the protocol that connects the SIP connector with the SIP trunk. Available options are UDP, TCP, and TLS.

    4. If your SIP trunk requires a registration request, select the Register? checkbox.

    5. Enter the following information provided by your SIP provider:

      • Username
      • Password
      • Authorization ID
      • Outbound Proxy
      • Default Register Expiry
      Tip

      The Default Register Expiry is 300 seconds if not provided, and applies to most use cases. It's possible that your SIP provider requires a different time. If so, enter it in the field.

    Map Inbound Calls Statically

    You can map incoming SIP Invites to specific channels of your app. For example, you can map a phone number to an online meeting room so that users can dial into the meeting.

    1. In the LiveSwitch Console > Applications > SIP Inbound Mapping Configuration section, click NEW to add a new mapping.
    2. In the URI field, enter the SIP invite identifier, such as the call-in phone number for an online meeting if you are using a SIP trunk provided by a third-party provider. The URI must be a registered number from your SIP provider.
    3. In the Channel field, enter the ID of the channel that maps to the SIP invite.

    Customize Outbound Caller ID

    By default, the SIP Connector uses username as the caller ID when placing outbound calls. However, certain SIP providers, such as Twilio, require the caller ID to be either a Twilio-purchased number or a verified number. You can customize the outbound caller ID to meet this kind of requirement. To do so, in the LiveSwitch Console > Applications > Channels > SIP Outbound Caller ID Configuration section, enter Display Name Pattern and Number Pattern. You can set those two patterns using the curly brace template format with the properties from the object. For example, {UserAlias}-{UserId}.

    Customize Dial Plan Using Webhooks

    Webhooks are user-defined HTTP callbacks that can send event-triggered notifications or updates to an external web server. You can use webhooks to hook your own processing into LiveSwitch events. LiveSwitch sends out webhook event updates as an HTTP POST request with the body formatted in JSON.

    You can use webhook to map inbound calls, route outbound calls, and get notified by canceled calls from LiveSwitch SIP Connector.

    Map Inbound Calls Dynamically

    You can use a webhook to dynamically map inbound calls according to your app's logic in addition to the static mapping. For example, you can create logic to map incoming calls to available agents for a call center app. When a call comes in, and the available agent is found, you create a new meeting room for that agent and maps the call into the room.

    To map inbound calls, in the LiveSwitch Console > Deployments > SIP Configuration section, enter your Webhook Inbound URL. If an inbound call does't match any static mapping, LiveSwitch sends an HTTP POST request to the provided webhook URL. Your webhook must return the application and channel for mapping the calls.

    The HTTP request is a Content-Type of application/json. The JSON object includes the following properties:

    Property Type Description
    headers JSON The headers from the inbound INVITE message.
    sdp string The SDP offer from the inbound INVITE message.

    An example request looks like the following:

    {
      "headers": {
        "From": "\"LiveSwitch \" <sip:frozenmountain@10.0.0.0>",
        "Content-Type": "application/sdp",
        ...
      },
      "sdp": "v=0\r\no=alice 2890844526 2890844526 IN IP4 host.atlanta.example.com..."
    }
    

    Your webhook HTTP response must be the Content-Type of application/json with the following properties:

    Property Type Required Description
    applicationId string Required ID of the application that maps to the call.
    channelId string Required ID of the channel that maps to the call.
    userId string Optional ID of the user for channel-level upstream connection open/close notifications. Defaults to the URI in the "From" header in the inbound INVITE message.

    An example response looks like the following:

    {
      "applicationId": "my-app",
      "channelId": "581233",
      "userId": "john@doe.com"
    }
    

    Get Notified of Canceled Calls

    To get notified of canceled calls using a webhook, in the LiveSwitch Console > Deployments > SIP Configuration, enter your Webhook Inbound Cancel URL. If an inbound call is canceled, LiveSwitch sends an HTTP POST request to the provided URL. Your webhook response doesn't need to contain any information.

    The HTTP request is a Content-Type of application/JSON. The JSON object includes the following properties:

    Property Type Description
    headers JSON The headers from the inbound INVITE message.

    An example looks like the following:

    {
      "headers": {
        "From": "\"Frozen Mountain\" <sip:frozenmountain@10.0.0.0>",
        "Content-Type": "application/sdp",
        ...
      }
    }
    

    Route Outbound Calls

    If you have configured more than one SIP trunk, LiveSwitch routes the outbound calls to the first available one. You can use webhook to route outbound calls to the specified SIP trunk. For example, suppose you have SIP trunks configured for different regions. You probably want to route calls originated from Europe using the SIP trunk configured for Europe to avoid long-distance calls.

    To route outbound calls, in the LiveSwitch Configuration Console > Application > SIP Configuration section, enter your Webhook Outbound URL. If an outbound call happens, LiveSwitch sends an HTTP POST request to the provided URL. Your webhook must return the SIP trunk ID for making the outbound call.

    The HTTP request body is a Content-Type of application/json. The JSON object includes the following properties:

    Property Type Description
    applicationId string ID of the application where the outbound call originates.
    channelId string ID of the channel where the outbound call originates.
    clientId string ID of the client where the outbound call originates.
    userId string ID of the user who originates the call.
    sipTrunks JSON array List of all SIP trunks you have configured in LiveSwitch. If your webhook already knows the SIP trunk IDs, and you don't want to include the trunk list in the request, select the Exclude SIP Trunks checkbox.
    id string ID of the SIP trunk.
    authId string Authentication ID of the SIP trunk.
    username string Username of the SIP trunk.
    domain string Domain name of the SIP trunk.

    An example response looks like the following:

    {
      "applicationId": "my-app",
      "channelId": "581233",
      "clientId": "my_client_id",
      "userId": "john@doe.com",
      "sipTrunks":[
         {
            "id": "my-sip-trunk-1",
            "authId": "dfsdf1234",
            "username": "my_sip_user1",
            "domain": "www.domain1.com"
         },
         {
            "id": "my-sip-trunk-2",
            "authId": "dfsdf1234dsd",
            "username": "my_sip_user2",
            "domain": "www.domain2.com"
         }
         ]
    }
    

    Your webhook HTTP response must be a Content-Type of application/json with the following properties:

    Property Type Required Description
    sipTrunkId string Required ID of the SIP trunk to route the call.

    An example response looks like the following:

    {
      "sipTrunkId": "my-sip-trunk-2"
    }
    

    Configure SIP Connector Ports

    You can configure the port that the SIP Connector uses to communicate with the SIP trunks. To do so, in the LiveSwitch Console > Deployments > SIP Configuration section, enter the Port.

    Note

    Unless you have a specific reason, you should use the default value of 5060 because most SIP trunks use this value.

    Signature Secret

    You can enter a signature secret to be used to route inbound calls into the SIP Connector with the Application ID and Channel ID in the headers. Signature secret is like a password and you can use any characters for it. For more information on how to use it, refer to the Request Signatures section in the SIP IVR Routing topic.

    In This Article
    Back to top Copyright © LiveSwitch Inc. All Rights Reserved.Documentation for LiveSwitch Version 1.16.2