Skip to main content
Normalized for Mintlify from knowledge-base/aiconnected-apps-and-modules/modules/aiConnected-voice/GoToConnect-integration-spec.mdx.

Voice by aiConnected — GoToConnect Integration Specification \

Document Information \


Table of Contents \

Voice by aiConnected — GoToConnect Integration Specification Document Information Table of Contents 1. Introduction 1.1 Purpose 1.2 Scope 1.3 Prerequisites 1.4 API Versions 2. GoToConnect Platform Overview 2.1 Architecture Context 2.2 Key Concepts 2.2.1 Lines and Extensions 2.2.2 Users and Accounts 2.2.3 Web Calls 2.2.4 Call Events 2.3 Our Integration Points 3. Authentication and Authorization 3.1 OAuth 2.0 Overview 3.2 OAuth Application Setup 3.2.1 Register Application 3.2.2 Create Service User 3.3 Token Management 3.3.1 Token Request 3.3.2 Token Response Structure 3.4 Required Scopes 3.5 Authentication Error Handling 4. WebRTC Integration 4.1 WebRTC Overview 4.2 Web Calls API 4.2.1 API Base Configuration 4.2.2 Initiate Outbound Call 4.2.3 Answer Inbound Call 4.3 SDP Exchange 4.3.1 SDP Offer Structure (from GoToConnect) 4.3.2 SDP Answer Generation 4.3.3 Codec Preferences 4.4 ICE Candidate Exchange 4.4.1 Trickle ICE 4.4.2 Handling Remote ICE Candidates 4.5 Audio Stream Handling 4.5.1 Receiving Audio from GoToConnect 4.5.2 Sending Audio to GoToConnect 5. Call Control API 5.1 Call Control Operations 5.1.1 Hold Call 5.1.2 Resume Call 5.1.3 Mute/Unmute 5.1.4 Send DTMF 5.1.5 Hang Up 5.2 Transfer Operations 5.2.1 Blind Transfer 5.2.2 Warm Transfer (Attended Transfer) 5.2.3 Conference (Merge Calls) 5.3 Call Control State Machine 5.4 Call Control Client 6. Event Subscriptions 6.1 Event System Overview 6.2 Create Notification Channel 6.3 Subscribe to Events 6.4 WebSocket Connection 6.5 Event Types 6.5.1 call.ringing 6.5.2 call.connected 6.5.3 call.ended 6.5.4 call.held 6.5.5 call.resumed 6.5.6 call.transferred 6.5.7 call.ice_candidate 6.5.8 call.dtmf 6.6 Event Handler Implementation 6.7 Subscription Management 7. Phone Number Management 7.1 Lines API 7.1.1 List Lines 7.1.2 Get Line Details 7.2 Phone Number to Line Mapping 8. Error Handling 8.1 Error Categories 8.2 Error Response Handling 8.3 Retry Logic 8.4 WebSocket Reconnection 9. Rate Limits and Quotas 9.1 GoToConnect Rate Limits 9.2 Rate Limit Handling 9.3 Quota Monitoring 10. Security Considerations 10.1 Credential Storage 10.2 Token Security 10.3 WebSocket Security 10.4 Audit Logging 11. Testing Strategy 11.1 Mock Server 11.2 Integration Tests 11.3 Unit Tests 12. Implementation Guide 12.1 Setup Checklist 12.2 Configuration Template 12.3 Service Initialization 13. Troubleshooting 13.1 Common Issues Authentication Failures WebRTC Issues Event Subscription Issues 13.2 Diagnostic Commands 13.3 Debug Logging 14. API Reference Summary 14.1 Authentication API 14.2 Web Calls API 14.3 Call Events API 14.4 Users/Lines API Appendix A: SDP Templates A.1 Minimal SDP Offer A.2 Full SDP Offer (GoToConnect) Appendix B: Event Schemas B.1 Common Event Structure B.2 Event Type Reference Document History

  1. Introduction \

1.1 Purpose \

This document provides a comprehensive specification for integrating Voice by aiConnected with GoToConnect’s telephony platform. It covers authentication, WebRTC session management, call control operations, and real-time event handling. GoToConnect serves as our PSTN gateway, providing:
  • Inbound and outbound call connectivity
  • WebRTC-based audio transport
  • Call control operations (transfer, hold, merge)
  • Real-time call event notifications

1.2 Scope \

This document covers:
  • OAuth 2.0 authentication flow with GoToConnect
  • WebRTC session establishment and management
  • Complete call control API mapping
  • WebSocket-based event subscription system
  • Error handling and recovery patterns
  • Security and compliance considerations
This document does not cover:
  • Internal service architecture (see ARCH-001)
  • LiveKit integration (see ARCH-003)
  • Voice pipeline implementation (see ARCH-004)

1.3 Prerequisites \

Before implementing this integration, ensure you have:
  • GoToConnect account with API access enabled
  • OAuth application registered in GoTo Developer Portal
  • Understanding of WebRTC fundamentals
  • Familiarity with OAuth 2.0 flows

1.4 API Versions \


  1. GoToConnect Platform Overview \

2.1 Architecture Context \

2.2 Key Concepts \

2.2.1 Lines and Extensions \

In GoToConnect, a line represents a phone endpoint:
  • Each line has a unique extension number
  • Lines can have one or more associated phone numbers (DIDs)
  • Our AI agents will be assigned to specific lines

2.2.2 Users and Accounts \

  • Account: The top-level organizational entity
  • User: An individual with login credentials
  • Service User: A programmatic user for API access (what we use)

2.2.3 Web Calls \

GoToConnect’s Web Calls API enables browser-based calling:
  • Provides WebRTC signaling endpoints
  • Manages call state via REST
  • Supports full call control (hold, transfer, merge)

2.2.4 Call Events \

Real-time notifications delivered via WebSocket:
  • Call state changes (ringing, connected, ended)
  • DTMF tones
  • Recording status
  • Error conditions

2.3 Our Integration Points \


  1. Authentication and Authorization \

3.1 OAuth 2.0 Overview \

GoToConnect uses OAuth 2.0 for API authentication. For server-to-server integration, we use the Client Credentials flow with a Service User.

3.2 OAuth Application Setup \

3.2.1 Register Application \

  1. Navigate to GoTo Developer Portal
  2. Create a new OAuth application
  3. Configure the following settings:

3.2.2 Create Service User \

In GoToConnect Admin Portal:
  1. Create a dedicated user for API access
  2. Assign appropriate permissions:
    • Make and receive calls
    • Access to required lines/extensions
    • API access enabled
  3. Store credentials securely:

3.3 Token Management \

3.3.1 Token Request \

3.3.2 Token Response Structure \

3.4 Required Scopes \

3.5 Authentication Error Handling \


  1. WebRTC Integration \

4.1 WebRTC Overview \

GoToConnect provides WebRTC endpoints for browser-based calling. Our WebRTC Bridge uses these to establish audio connections with callers.

4.2 Web Calls API \

4.2.1 API Base Configuration \

4.2.2 Initiate Outbound Call \

Request:
Response:

4.2.3 Answer Inbound Call \

Request:
Response:

4.3 SDP Exchange \

4.3.1 SDP Offer Structure (from GoToConnect) \

4.3.2 SDP Answer Generation \

4.3.3 Codec Preferences \

GoToConnect supports multiple audio codecs. We prefer Opus for quality:

4.4 ICE Candidate Exchange \

4.4.1 Trickle ICE \

GoToConnect supports trickle ICE, allowing candidates to be exchanged incrementally:
Request:

4.4.2 Handling Remote ICE Candidates \

ICE candidates from GoToConnect arrive via WebSocket events:

4.5 Audio Stream Handling \

4.5.1 Receiving Audio from GoToConnect \

4.5.2 Sending Audio to GoToConnect \


  1. Call Control API \

5.1 Call Control Operations \

5.1.1 Hold Call \

Place the remote party on hold (they hear hold music).
Request:
Response:

5.1.2 Resume Call \

Resume a held call.
Request:

5.1.3 Mute/Unmute \

Control the microphone (our audio to the caller).

5.1.4 Send DTMF \

Send touch-tone digits.
Request:

5.1.5 Hang Up \

End the call.

5.2 Transfer Operations \

5.2.1 Blind Transfer \

Transfer the call immediately without consulting the target.
Request:
Response:
Request:

5.2.3 Conference (Merge Calls) \

Add a third party to an existing call.
Request:

5.3 Call Control State Machine \

5.4 Call Control Client \

Complete client implementation:

  1. Event Subscriptions \

6.1 Event System Overview \

GoToConnect provides real-time events via WebSocket. Events notify us of call state changes, allowing reactive handling.

6.2 Create Notification Channel \

Request:
Response:

6.3 Subscribe to Events \

Request:
Response:

6.4 WebSocket Connection \

6.5 Event Types \

6.5.1 call.ringing \

Fired when an inbound call arrives.

6.5.2 call.connected \

Fired when a call is answered.

6.5.3 call.ended \

Fired when a call ends.
End Reasons: | Reason | Description | |--------|-------------| | caller_hangup | Remote party hung up | | agent_hangup | We hung up | | transfer | Call was transferred | | timeout | Call timed out | | error | Call failed due to error | | busy | Remote party was busy | | no_answer | Remote party didn’t answer | | rejected | Call was rejected |

6.5.4 call.held \

Fired when a call is placed on hold.

6.5.5 call.resumed \

Fired when a held call is resumed.

6.5.6 call.transferred \

Fired when a call is transferred.

6.5.7 call.ice_candidate \

Fired when a new ICE candidate is available.

6.5.8 call.dtmf \

Fired when DTMF tones are received.

6.6 Event Handler Implementation \

6.7 Subscription Management \


  1. Phone Number Management \

7.1 Lines API \

7.1.1 List Lines \

Response:

7.1.2 Get Line Details \

7.2 Phone Number to Line Mapping \

We need to map incoming phone numbers to our tenant/agent configuration:

  1. Error Handling \

8.1 Error Categories \

8.2 Error Response Handling \

8.3 Retry Logic \

8.4 WebSocket Reconnection \


  1. Rate Limits and Quotas \

9.1 GoToConnect Rate Limits \

9.2 Rate Limit Handling \

9.3 Quota Monitoring \


  1. Security Considerations \

10.1 Credential Storage \

10.2 Token Security \

10.3 WebSocket Security \

10.4 Audit Logging \


  1. Testing Strategy \

11.1 Mock Server \

11.2 Integration Tests \

11.3 Unit Tests \


  1. Implementation Guide \

12.1 Setup Checklist \

12.2 Configuration Template \

12.3 Service Initialization \


  1. Troubleshooting \

13.1 Common Issues \

Authentication Failures \

WebRTC Issues \

Event Subscription Issues \

13.2 Diagnostic Commands \

13.3 Debug Logging \


  1. API Reference Summary \

14.1 Authentication API \

14.2 Web Calls API \

14.3 Call Events API \

14.4 Users/Lines API \


A.2 Full SDP Offer (GoToConnect) \

See Section 4.3.1 for complete example.

B.2 Event Type Reference \

See Section 6.5 for complete event schemas.

Document History \


End of Document