> ## Documentation Index
> Fetch the complete documentation index at: https://docs.g-tateth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice & Phone API

> Complete guide to integrating voice and phone capabilities with G-Tateth

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

<Note>
  All API endpoints are documented in the [API Reference](/api-reference) tab. This guide focuses on concepts, workflows, and integration examples.
</Note>

## Quick Start

### 1. Configure Phone Service

First, set up your phone service in your dashboard or via the [Configure Phone Service](/api-reference/telephony/configure) 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:**

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

**Optional Settings:**

```json theme={null}
{
  "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](/api-reference/telephony/calls/initiate) 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](/api-reference/telephony/calls/incoming) endpoint is called automatically by G-Tateth when a call comes in.

<Warning>
  You don't need to call this endpoint directly. It's a webhook endpoint that G-Tateth calls automatically.
</Warning>

**Webhook Payload:**

```json theme={null}
{
  "from": "+2348012345678",
  "to": "+2348098765432",
  "callSid": "CA1234567890"
}
```

## Call Management

### Get Call History

Retrieve call history with filtering and pagination using the [Get Call History](/api-reference/telephony/calls/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](/api-reference/telephony/calls/\{callId}/metadata) endpoint.

**Request Body:**

```json theme={null}
{
  "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](/api-reference/telephony/calls/\{callId}/recording/download) endpoint.

### Stream Recording

Stream call recording audio directly using the [Stream Recording](/api-reference/telephony/calls/\{callId}/recording/stream) endpoint.

### Delete Recording

Permanently delete a call recording using the [Delete Recording](/api-reference/telephony/calls/\{callId}/recording) endpoint.

<Warning>
  This action cannot be undone. The recording will be permanently deleted.
</Warning>

## IVR (Interactive Voice Response)

### Create IVR Menu

Create interactive voice response menus using the [Create IVR Menu](/api-reference/telephony/ivr/menus) endpoint.

**Menu Options Example:**

```json theme={null}
{
  "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 IVR Menu

Update existing IVR menus using the [Update IVR Menu](/api-reference/telephony/ivr/menus/\{menuId}) endpoint.

## WebRTC Integration

### Get Capability Token

Generate a capability token for WebRTC calls using the [Get WebRTC Capability Token](/api-reference/telephony/webrtc/capability-token) endpoint.

**Request:**

```json theme={null}
{
  "agentId": "agent-123",
  "customerPhone": "+2348012345678"
}
```

**Response:**

```json theme={null}
{
  "capabilityToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "clientName": "agent-name"
}
```

### WebRTC Call Flow

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

**Example JavaScript Implementation:**

```javascript theme={null}
// 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](/api-reference/telephony/queue/status) endpoint.

**Response:**

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```javascript theme={null}
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

```python theme={null}
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

```bash theme={null}
# 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

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

### Recordings Not Available

1. Verify recording is enabled
2. Check recording settings in your dashboard
3. Wait for processing delay
4. Check storage permissions

### WebRTC Issues

1. Verify capability token validity
2. Check browser WebRTC support
3. Ensure proper firewall configuration
4. Review network connectivity

## Support

Need help? Contact us:

* **Email**: [support@g-tateth.com](mailto:support@g-tateth.com)
* **Documentation**: [https://docs.g-tateth.com](https://docs.g-tateth.com)
* **Dashboard**: [https://app.g-tateth.com](https://app.g-tateth.com)