Initiating Outbound Calls on Behalf of an Agent via API

StarAdmin · May 22, 2026, 9:00am

Initiating Outbound Calls on Behalf of an Agent via API

What You Will Build

This tutorial demonstrates how to programmatically initiate an outbound voice call from a Genesys Cloud user account using the REST API. You will learn how to construct the request payload, handle the required OAuth scopes, and manage the asynchronous nature of the call initiation process. The implementation uses Python and the official Genesys Cloud Python SDK.

Prerequisites

A Genesys Cloud organization with the Voice product enabled.
A Genesys Cloud user account with the Agent role (or a custom role with conversation:call:write permissions).
An OAuth 2.0 Client ID and Client Secret with the following scopes:
- conversation:call:write
- conversation:call:read
- user:read (optional, if retrieving user details dynamically)
Python 3.8 or higher.
The genesyscloud Python SDK installed (pip install genesyscloud).

Authentication Setup

Genesys Cloud APIs use OAuth 2.0 for authentication. For server-to-server integrations or automated scripts, the Client Credentials flow is the standard approach. This flow requires a registered Application in the Genesys Cloud Admin Portal.

The Python SDK handles token acquisition and refresh automatically when you initialize the PlatformClient. You must provide the client_id, client_secret, and base_url (which includes your environment, e.g., mypurecloud.com).

import os
from purecloudplatformclientv2 import (
    Configuration,
    ApiClient,
    PlatformClient,
    ConversationApi,
    OutboundCallRequest
)

def get_platform_client():
    """
    Initializes and returns the Genesys Cloud Platform Client.
    """
    config = Configuration(
        client_id=os.getenv("GENESYS_CLIENT_ID"),
        client_secret=os.getenv("GENESYS_CLIENT_SECRET"),
        base_url=os.getenv("GENESYS_BASE_URL", "https://api.mypurecloud.com")
    )
    api_client = ApiClient(configuration=config)
    platform_client = PlatformClient(api_client=api_client)
    return platform_client

Note: Ensure your environment variables are set before running the script. The base_url must match the specific environment of your Genesys Cloud instance (e.g., api.usw2.pure.cloud for US West 2).

Implementation

Step 1: Prepare the Call Request Payload

The core of this operation is the POST /api/v2/conversations/calls endpoint. This endpoint accepts a JSON body that defines the type of conversation, the participants, and the direction of the call.

For an outbound call, the type must be set to voice. The from object represents the initiator (usually the agent or an automated user), and the to object represents the destination (the customer).

The to object requires a phoneNumber and a name. The name is not strictly required by the API engine for routing but is highly recommended for display purposes in the Genesys Cloud UI and for audit logs.

def create_outbound_call_request(from_user_id: str, to_phone_number: str, to_name: str) -> OutboundCallRequest:
    """
    Constructs the OutboundCallRequest object.
    
    Args:
        from_user_id: The Genesys Cloud User ID of the agent initiating the call.
        to_phone_number: The E.164 formatted phone number to call.
        to_name: The display name for the destination number.
    
    Returns:
        OutboundCallRequest: The payload object for the API.
    """
    # Define the 'from' participant (The Agent/User)
    from_participant = {
        "id": from_user_id,
        "name": "Agent Caller", # This can be dynamic if you fetch user details
        "phoneNumber": None # Not required for 'from' if it is a platform user
    }

    # Define the 'to' participant (The Customer)
    to_participant = {
        "id": None, # Not required for external numbers
        "name": to_name,
        "phoneNumber": to_phone_number
    }

    # Construct the request body
    request_body = {
        "type": "voice",
        "from": from_participant,
        "to": to_participant,
        "wrapupCode": None, # Optional: Pre-assign a wrap-up code
        "customDispositions": [] # Optional: Custom dispositions
    }
    
    return OutboundCallRequest.from_dict(request_body)

Key Parameter Details:

type: Must be voice for phone calls. Other types include chat, email, sms, etc.
from.id: This is critical. If you provide a valid Genesys Cloud User ID here, the call appears in that user’s conversation history and adheres to their routing configuration (if applicable). If you use a generic system user, ensure that user has the necessary permissions to make calls.
to.phoneNumber: Must be in E.164 format (e.g., +14155550199). Invalid formats will result in a 400 Bad Request.

Step 2: Execute the API Call

The ConversationApi class provides the post_conversations_call method. This method sends the request to Genesys Cloud and returns a Conversation object immediately.

Important: The API response indicates that the call has been initiated, not that it has been answered. The state field in the response will typically be initiated or ringing. You must handle the asynchronous nature of this operation if you need to know the final outcome (answered, busy, no-answer).

def initiate_call(platform_client: PlatformClient, call_request: OutboundCallRequest) -> dict:
    """
    Initiates the outbound call using the Conversation API.
    
    Args:
        platform_client: The initialized PlatformClient.
        call_request: The OutboundCallRequest object.
    
    Returns:
        dict: The JSON response from the API.
    
    Raises:
        purecloudplatformclientv2.rest.ApiException: If the API request fails.
    """
    conversation_api = ConversationApi(platform_client)
    
    try:
        # Execute the API call
        response = conversation_api.post_conversations_call(body=call_request)
        
        # Convert the response object to a dictionary for easier handling
        response_dict = response.to_dict()
        
        print(f"Call initiated successfully. Conversation ID: {response_dict.get('id')}")
        print(f"Current State: {response_dict.get('state')}")
        
        return response_dict
        
    except Exception as e:
        # Handle API errors
        if hasattr(e, 'body'):
            error_body = e.body
            print(f"API Error Status: {e.status}")
            print(f"API Error Body: {error_body}")
        else:
            print(f"Unexpected Error: {str(e)}")
        raise

Step 3: Handling Errors and Validation

Genesys Cloud APIs return standard HTTP status codes. Common errors for this endpoint include:

400 Bad Request: Invalid phone number format, missing required fields, or invalid User ID.
401 Unauthorized: Invalid or expired OAuth token.
403 Forbidden: The user does not have the conversation:call:write scope or permission.
429 Too Many Requests: Rate limit exceeded. Implement exponential backoff.

The Python SDK raises an ApiException for any non-2xx response. You should catch this exception and inspect the status and body attributes to diagnose the issue.

def handle_api_error(exception: Exception) -> None:
    """
    Parses and logs API errors from the Genesys Cloud SDK.
    """
    if isinstance(exception, purecloudplatformclientv2.rest.ApiException):
        status_code = exception.status
        error_body = exception.body
        
        if status_code == 400:
            print("Bad Request: Check your phone number format and payload structure.")
        elif status_code == 401:
            print("Unauthorized: Check your Client ID and Secret.")
        elif status_code == 403:
            print("Forbidden: Ensure the user has 'conversation:call:write' permissions.")
        elif status_code == 429:
            print("Rate Limited: Wait before retrying.")
        else:
            print(f"API Error {status_code}: {error_body}")
    else:
        print(f"Non-API Error: {str(exception)}")

Complete Working Example

The following script combines all steps into a single, runnable module. It assumes you have set the environment variables GENESYS_CLIENT_ID, GENESYS_CLIENT_SECRET, and GENESYS_BASE_URL.

import os
import sys
from purecloudplatformclientv2 import (
    Configuration,
    ApiClient,
    PlatformClient,
    ConversationApi,
    OutboundCallRequest,
    ApiException
)

def get_platform_client():
    """Initializes the Genesys Cloud Platform Client."""
    config = Configuration(
        client_id=os.getenv("GENESYS_CLIENT_ID"),
        client_secret=os.getenv("GENESYS_CLIENT_SECRET"),
        base_url=os.getenv("GENESYS_BASE_URL", "https://api.mypurecloud.com")
    )
    api_client = ApiClient(configuration=config)
    return PlatformClient(api_client=api_client)

def create_outbound_call_request(from_user_id: str, to_phone_number: str, to_name: str) -> OutboundCallRequest:
    """Constructs the OutboundCallRequest object."""
    from_participant = {
        "id": from_user_id,
        "name": "API Caller",
        "phoneNumber": None
    }

    to_participant = {
        "id": None,
        "name": to_name,
        "phoneNumber": to_phone_number
    }

    request_body = {
        "type": "voice",
        "from": from_participant,
        "to": to_participant,
        "wrapupCode": None
    }
    
    return OutboundCallRequest.from_dict(request_body)

def initiate_outbound_call(from_user_id: str, to_phone_number: str, to_name: str) -> None:
    """
    Main function to initiate an outbound call.
    """
    try:
        # 1. Initialize Client
        platform_client = get_platform_client()
        
        # 2. Prepare Payload
        call_request = create_outbound_call_request(from_user_id, to_phone_number, to_name)
        
        # 3. Execute API Call
        conversation_api = ConversationApi(platform_client)
        response = conversation_api.post_conversations_call(body=call_request)
        
        # 4. Process Response
        response_dict = response.to_dict()
        conversation_id = response_dict.get('id')
        state = response_dict.get('state')
        
        print(f"Success: Call initiated.")
        print(f"Conversation ID: {conversation_id}")
        print(f"State: {state}")
        
    except ApiException as e:
        print(f"API Exception occurred: Status {e.status}")
        print(f"Error Body: {e.body}")
        sys.exit(1)
    except Exception as e:
        print(f"Unexpected error: {str(e)}")
        sys.exit(1)

if __name__ == "__main__":
    # Configuration
    AGENT_USER_ID = os.getenv("AGENT_USER_ID")  # Replace with your actual User ID
    TARGET_PHONE = "+14155550199"  # Replace with a valid E.164 number
    TARGET_NAME = "Customer Support"

    if not AGENT_USER_ID:
        print("Error: AGENT_USER_ID environment variable is not set.")
        sys.exit(1)

    initiate_outbound_call(AGENT_USER_ID, TARGET_PHONE, TARGET_NAME)

Common Errors & Debugging

Error: 400 Bad Request - “Invalid phone number”

Cause: The to.phoneNumber field does not conform to E.164 standards.
Fix: Ensure the number starts with + and contains only digits. For example, use +14155550199 instead of (415) 555-0199 or 4155550199.

Code Check:

# Incorrect
"phoneNumber": "4155550199"
# Correct
"phoneNumber": "+14155550199"

Error: 403 Forbidden - “Insufficient permissions”

Cause: The OAuth token associated with the Client ID does not include the conversation:call:write scope, or the User ID provided in the from object does not have the agent role.
Fix:
1. Verify the OAuth Client in the Genesys Cloud Admin Portal has the correct scopes.
2. Verify the AGENT_USER_ID belongs to a user with the Agent role.
3. Ensure the user is not suspended or inactive.

Error: 429 Too Many Requests

Cause: You have exceeded the rate limit for the POST /api/v2/conversations/calls endpoint.
Fix: Implement exponential backoff. The Genesys Cloud API returns a Retry-After header in the response.

Code Example:

import time

def make_call_with_retry(platform_client, call_request, max_retries=3):
    for attempt in range(max_retries):
        try:
            conversation_api = ConversationApi(platform_client)
            return conversation_api.post_conversations_call(body=call_request)
        except ApiException as e:
            if e.status == 429:
                retry_after = e.headers.get('Retry-After', 1)
                print(f"Rate limited. Waiting {retry_after} seconds...")
                time.sleep(int(retry_after))
            else:
                raise
    raise Exception("Max retries exceeded")

Initiating Outbound Calls on Behalf of an Agent via API

Initiating Outbound Calls on Behalf of an Agent via API

What You Will Build

Prerequisites

Authentication Setup

Implementation

Step 1: Prepare the Call Request Payload

Step 2: Execute the API Call

Step 3: Handling Errors and Validation

Complete Working Example

Common Errors & Debugging

Error: 400 Bad Request - “Invalid phone number”

Error: 403 Forbidden - “Insufficient permissions”

Error: 429 Too Many Requests

Official References