Integration with IP telephony

The system includes out-of-the-box integrations with various IP telephony providers. If your specific integration is not available, you can use this API to create your own custom integration. To do this, create a custom module and implement a few functions in the module scripts using TypeScript.
Built-in and custom telephony integration modules are functionally identical. Your custom module will have access to the following features:

• Initiating outgoing calls from the system via the context menu of a Phone field;
• Displaying a call page with brief client information and call control buttons when receiving an incoming call or initiating an outgoing call;
• Opening a summary page with client information;
• Automatically creating and saving an app item if a call is missed and the number is not found in the database;
• Logging missed calls;
• Logging incoming/outgoing call messages in the activity stream of an item. If the call was answered, a link to the call recording is attached and can be played in the interface. You can pllay the recording in the interface and also add comments (e.g., call summary);
• Automatically creating a Call app item in the Telephony workspace for each call;
• Mapping IP telephony users to system users for routing and correctly displaying which operator handled the call.

  Limiations

  Before implementing a telephony integration module, note the following API limitations:

1.Call routing is not handled by the system to avoid conflicts with the provider’s own routing settings. Most providers support routing to an employee or group, after which the incoming call is shown in the system for the specified users. 2. Currently, telephony events are processed via HTTP webhook delivery. ЕIf your provider doesn't support webhooks, you must create an intermediate service to convert the provider's format into a request to the system. To do that you can create a [portable service in a module.](https://brix365. com/en/help/platform/portable-microservices.html) 3. Only call recording links are stored.Most providers store call recordings and give you a link,
but make sure to check their file retention policies — the recodring may not be available after a certain time.

To create a telephony integration module, implement the following functions in your custom module script:

// Test the telephony connection.  Called when clicking **Test Connection** in the module settings 
// Returns  the connection test status, which is shown to the user on the module page  
async function VoipTestConnection(): Promise<VoipTestConnectionResult> { }  
// Handle the IP telephony provder's request. Called when there is a  request sent to the module's webhook 
// In the `request` parameter data  about the HTTP request is stored, including HTTP headers and the request  body 
// The function returns the result of processing the request, based on  which the system will display notifications 
// about incoming calls, save  the call recording, etc. 
async function VoipParseWebhookRequest(request:  FetchRequest): Promise<VoipWebhookParseResult> { } 
// Get a list of users  from the IP telephony provider 
// Called when mapping telephony users to  system users after clicking the **Configure** button on the module page 
//  Returns a list of users from the IP telephony provider 
async function  VoipGetMembers(): Promise<VoipMember[]> { } 
// Generate an outgoing call.  This function is called when a system user clicks the call button 
//in the  context menu of a **Phone** field or when clicking the **Call back** button  in the call page. In parameter 
// `srcPhone` specifies the caller's number,  
`dstPhone` is the number to call 
async function VoipGenerateCall(srcPhone:  string, dstPhone: string): Promise<void> { } 
// Get a link to the call  recording. This function is called when a system user plays the call  recording from 
// the app item's activity stream or when saving the link to  the recording in the context of the **Call** app item 
// of the  **Telephony** workspace. The `callData` parameter contains the data  specified when saving 
// the call recording information from the  `VoipParseWebhookRequest` function. The function must return a file link  
async function VoipGetCallLink(callData: any): Promise<string> { } 
//  Automatically called when the webhook URL changes (for example, when the  token is updated) 
// Parameter “webhookUrl” contains the absolute URL of  the integration module webhook. Implementation is optional 
async function  VoipOnWebhookUpdated(webhookUrl: string): Promise<void> { } 

After implementing these functions and saving the script on the module pag, you will see a new workspace called Telephony Settings. In this workspace, a webhook URL will be provided — when data is sent to this URL, the
VoipParseWebhookRequest is called from the script. In that function, you should handle the request and return an instance of VoipWebhookParseResult ased on which the system will display incoming call notifications or save information about the call recording. You need to specify the webhook URL in your telephony provider's settings. The URL handles the GET and POST HTTP requestst. It must also include a required token parameter.

When an incoming or outgoing call occurs, the system user will see [a page with call info](https://brix365. com/en/help/crm/work-with-call.html) in the bottom right corner. Depending on the call state, different buttons may appear in the page: accept call,
end call, reassign to another operator, and so on. To display these buttons, you need to implement the following functions in the custom telephony module:

// Accept a call. You must start  transmitting voice data between the operator and the client. This function  
// is called when the system user clicks the **Accept Call** button in the  call page. The `srcPhone` parameter 
// specifies the caller's number, and  `dstPhone` — the number the call is directed to 
async function  VoipAcceptCall(srcPhone: string, dstPhone: string): Promise<void> { } 
//  End a call. You must terminate the call between the operator and the client.  This function is called when 
// the system user clicks the **End Call**  button in the call page. The `srcPhone` parameter specifies 
// the caller's  number, and `dstPhone` — the number the call is directed to 
async function  VoipHangupCall(srcPhone: string, dstPhone: string): Promise<void> { } 
//  Redirect a call. You must terminate the current operator's call and connect  the client to another 
// operator. This function is called when the system  user clicks the Redirect button in 
// the call's page. The `srcPhone`  parameter specifies the caller's number, `dstPhone` — the call target, 
//  `redirectTo` is the internal number of the operator to redirect the call to  
async function VoipRedirectCall(srcPhone: string, dstPhone: string,  redirectTo: string): Promise<void> { } 
// Put a call on hold. You must  pause voice data transmission between the operator and the client without 
//  ending the call. This function is called when the system user clicks the  Hold button 
// in the call's page. The `srcPhone` parameter specifies the  caller's number, `dstPhone` — the call target, 
// and for `hold` the value  `true` means the call should be put on hold, otherwise it will be resumed  
async function VoipHoldCall(srcPhone: string, dstPhone: string, hold:  boolean): Promise<void> { } 

If any of the above functions are not implemented in the custom telephony module, the corresponding button will not appear in the call page.