Voice & Phone API - G-Tateth API Documentation

The G-Tateth Voice & Phone API enables you to make and receive calls, manage call flows, record conversations, and integrate voice capabilities into your applications.

Overview

G-Tateth provides a unified voice and phone service that supports:

Phone Calls - Make and receive calls from anywhere in the world
WebRTC - Browser-based calling (no phone numbers needed)
Call Recording - Automatic recording and transcription
IVR Systems - Interactive voice response menus
Call Routing - Intelligent call distribution to agents

All API endpoints are documented in the API Reference tab. This guide focuses on concepts, workflows, and integration examples.

Quick Start

1. Configure Phone Service

First, set up your phone service in your dashboard or via the Configure Phone Service endpoint. Configuration Options:

phoneNumber - Your dedicated phone number
recordingEnabled - Enable automatic call recording
transcriptionEnabled - Enable call transcription
defaultCountryCode - Default country code for calls
webhookUrl - URL for receiving call events

Example Configuration:

{
  "phoneNumber": "+1234567890",
  "recordingEnabled": true,
  "transcriptionEnabled": true,
  "defaultCountryCode": "+1",
  "webhookUrl": "https://your-app.com/webhooks/telephony"
}

Optional Settings:

{
  "recordingEnabled": true,
  "transcriptionEnabled": true,
  "defaultCountryCode": "+234",
  "webhookUrl": "https://your-app.com/webhooks/telephony"
}

2. Initiate a Call

Make an outbound call using the Initiate Call endpoint. Required Parameters:

customerPhone - Customer phone number in E.164 format (e.g., +2348012345678)
agentId - ID of the agent making the call

Optional Parameters:

customerId - Existing customer ID (will create if not provided)
conversationId - Link call to existing conversation
customGreeting - Custom greeting message to play before connecting
recordingEnabled - Enable call recording (default: true)

Response: The endpoint returns a callId, conversationId, status, and optionally webRTC configuration if using WebRTC.

3. Handle Incoming Calls

Set up webhooks to receive incoming calls. The Handle Incoming Call endpoint is called automatically by G-Tateth when a call comes in.

You don’t need to call this endpoint directly. It’s a webhook endpoint that G-Tateth calls automatically.

Webhook Payload:

{
  "from": "+2348012345678",
  "to": "+2348098765432",
  "callSid": "CA1234567890"
}

Call Management

Get Call History

Retrieve call history with filtering and pagination using the Get Call History endpoint. Query Parameters:

startDate - Start date (ISO 8601 format)
endDate - End date (ISO 8601 format)
status - Filter by status: completed, missed, failed, answered
direction - Filter by direction: inbound, outbound
agentId - Filter by agent ID
customerId - Filter by customer ID
page - Page number (default: 1)
limit - Results per page (default: 20)

Update Call Metadata

Add notes, tags, or ratings to calls using the Update Call Metadata endpoint.

callId is the call record id returned by Get Call History, not the provider’s session id. A session id matches no call record, so the request returns 404 and the note is not saved.

Request Body:

{
  "notes": "Customer requested callback",
  "tags": ["important", "follow-up"],
  "rating": 5
}

Call Recording

Get Recording Download Link

Get a secure, time-limited download link for call recordings using the Get Recording Download Link endpoint.

Stream Recording

Stream call recording audio directly using the Stream Recording endpoint. The endpoint supports HTTP range requests, so players can seek, and a HEAD request returns the headers alone including Content-Length. Audio players cannot set request headers, so the access token may also be passed as a token query parameter. A 502 with code UPSTREAM_RECORDING_REFUSED means the stored file could not be read — typically an expired or malformed storage link. Retry the request to get a fresh one; if it persists, the recording needs investigating rather than retrying.

Delete Recording

Permanently delete a call recording using the Delete Recording endpoint.

This action cannot be undone. The recording will be permanently deleted.

IVR (Interactive Voice Response)

Create interactive voice response menus using the Create IVR Menu endpoint. Menu Options Example:

{
  "name": "Main Menu",
  "greeting": "Thank you for calling. Press 1 for sales, 2 for support, or 0 to leave a message.",
  "options": [
    {
      "digit": "1",
      "action": "route",
      "target": "sales-team",
      "message": "Press 1 for sales"
    },
    {
      "digit": "2",
      "action": "route",
      "target": "support-team",
      "message": "Press 2 for support"
    },
    {
      "digit": "0",
      "action": "voicemail",
      "message": "Press 0 to leave a message"
    }
  ],
  "timeout": 10
}

Update existing IVR menus using the Update IVR Menu endpoint.

WebRTC Integration

Get Capability Token

Generate a capability token for WebRTC calls using the Get WebRTC Capability Token endpoint. Request:

{
  "agentId": "agent-123",
  "customerPhone": "+2348012345678"
}

Response:

{
  "capabilityToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "clientName": "agent-name"
}

WebRTC Call Flow

Get capability token using the endpoint above
Initialize WebRTC client in your browser/application
Connect to WebRTC server using the token
Make or receive calls through the WebRTC connection

Example JavaScript Implementation:

// Get capability token
const response = await fetch('/api/telephony/webrtc/capability-token', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${yourToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agentId: 'agent-123',
    customerPhone: '+2348012345678'
  })
});

const { capabilityToken, clientName } = await response.json();

// Initialize WebRTC client (example using a WebRTC library)
const client = new WebRTCClient({
  token: capabilityToken,
  clientName: clientName
});

// Make call
await client.call(customerPhone);

Call Routing

Queue Status

Get current call queue status and wait times using the Get Queue Status endpoint. Response:

{
  "waitingCalls": 3,
  "availableAgents": 5,
  "averageWaitTime": 45
}

Routing Strategies

Configure call routing in your tenant settings:

Round-robin - Distribute calls evenly
Least-busy - Route to agent with fewest active calls
Random - Random assignment
Priority - Route to priority agents first

Webhooks

Receiving Call Events

G-Tateth can send call event webhooks to your application when calls are initiated, answered, completed, or when recordings are available. Configure Your Webhook URL: Set your webhook URL in your phone service configuration:

{
  "settings": {
    "webhookUrl": "https://your-app.com/webhooks/calls"
  }
}

Webhook Events: G-Tateth will send POST requests to your configured webhook URL with the following events:

call.initiated - Call has been initiated
call.ringing - Call is ringing
call.answered - Call has been answered
call.completed - Call has completed
call.failed - Call failed
call.recording.available - Call recording is available

Webhook Payload Example: When a call completes, G-Tateth will send a POST request to your webhook URL:

{
  "event": "call.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "callId": "call_1234567890",
    "conversationId": "conv_1234567890",
    "status": "completed",
    "duration": 120,
    "recordingUrl": "https://...",
    "from": "+2348012345678",
    "to": "+2348098765432",
    "direction": "outbound",
    "agentId": "agent_123"
  }
}

Webhook Signature Verification: Each webhook request includes an X-Webhook-Signature header for verification. Always verify signatures to ensure requests are from G-Tateth.

Code Examples

JavaScript/Node.js

const axios = require('axios');

// Initiate call
async function makeCall(customerPhone, agentId) {
  const response = await axios.post(
    'https://api.g-tateth.com/api/telephony/calls/initiate',
    {
      customerPhone,
      agentId,
      recordingEnabled: true,
      customGreeting: 'Thank you for calling!'
    },
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}

// Get call history
async function getCallHistory(startDate, endDate) {
  const response = await axios.get(
    'https://api.g-tateth.com/api/telephony/calls/history',
    {
      params: { startDate, endDate },
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    }
  );
  
  return response.data;
}

Python

import requests

# Initiate call
def make_call(customer_phone, agent_id, api_key):
    response = requests.post(
        'https://api.g-tateth.com/api/telephony/calls/initiate',
        json={
            'customerPhone': customer_phone,
            'agentId': agent_id,
            'recordingEnabled': True
        },
        headers={
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }
    )
    return response.json()

# Get call history
def get_call_history(start_date, end_date, api_key):
    response = requests.get(
        'https://api.g-tateth.com/api/telephony/calls/history',
        params={
            'startDate': start_date,
            'endDate': end_date
        },
        headers={
            'Authorization': f'Bearer {api_key}'
        }
    )
    return response.json()

cURL

# Initiate call
curl -X POST https://api.g-tateth.com/api/telephony/calls/initiate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerPhone": "+2348012345678",
    "agentId": "agent-123",
    "recordingEnabled": true
  }'

# Get call history
curl -X GET "https://api.g-tateth.com/api/telephony/calls/history?startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

Best Practices

Security

Always use HTTPS for webhooks
Validate webhook signatures from G-Tateth
Store credentials securely
Use environment variables for API keys

Performance

Implement retry logic for failed calls
Use async processing for webhooks
Cache capability tokens when possible
Monitor call queue status

User Experience

Provide clear call greetings
Set appropriate timeout values
Enable call recording for quality
Use IVR menus for complex routing

Troubleshooting

Calls Not Connecting

Verify phone service configuration
Check phone number format (E.164)
Ensure webhook URLs are accessible
Review call logs in your dashboard

Recordings Not Available

Verify recording is enabled
Check recording settings in your dashboard
Wait for processing delay
Check storage permissions

WebRTC Issues

Verify capability token validity
Check browser WebRTC support
Ensure proper firewall configuration
Review network connectivity

Call charges

Outbound calls are charged per second of connected time, at a rate set for your account. At the default rate of ₦0.28 per second:

Call length	Charge
30 seconds	₦8.40
60 seconds	₦16.80
90 seconds	₦25.20

Part-seconds are rounded down and a call that never connects is free. The amount is taken from your balance once the call completes, and appears as cost on the call record, in the currency given by currencyCode. Inbound calls are not charged by default. Both directions can be turned on or off for your account, and cost is left blank for a direction that is not charged.

Charges are based on your own rate, not on what the underlying carrier bills, so the figure on the call record is what you pay.

Support

Need help? Contact us:

Email: support@g-tateth.com
Documentation: https://docs.g-tateth.com
Dashboard: https://app.g-tateth.com

​Overview

​Quick Start

​1. Configure Phone Service

​2. Initiate a Call

​3. Handle Incoming Calls

​Call Management

​Get Call History

​Update Call Metadata

​Call Recording

​Get Recording Download Link

​Stream Recording

​Delete Recording

​IVR (Interactive Voice Response)

​Create IVR Menu

​Update IVR Menu

​WebRTC Integration

​Get Capability Token

​WebRTC Call Flow

​Call Routing

​Queue Status

​Routing Strategies

​Webhooks

​Receiving Call Events

​Code Examples

​JavaScript/Node.js

​Python

​cURL

​Best Practices

​Security

​Performance

​User Experience

​Troubleshooting

​Calls Not Connecting

​Recordings Not Available

​WebRTC Issues

​Call charges

​Support

Overview

Quick Start

1. Configure Phone Service

2. Initiate a Call

3. Handle Incoming Calls

Call Management

Get Call History

Update Call Metadata

Call Recording

Get Recording Download Link

Stream Recording

Delete Recording

IVR (Interactive Voice Response)

Create IVR Menu

Update IVR Menu

WebRTC Integration

Get Capability Token

WebRTC Call Flow

Call Routing

Queue Status

Routing Strategies

Webhooks

Receiving Call Events

Code Examples

JavaScript/Node.js

Python

cURL

Best Practices

Security

Performance

User Experience

Troubleshooting

Calls Not Connecting

Recordings Not Available

WebRTC Issues

Call charges

Support