menu logo

API/Voicebot/Conversation Call

Place a conversation workflow call request to initiate interactive voice conversations.

  1. Send a conversation workflow request and receive a batch ID
  2. Use the batch ID to track the processing status of your conversation requests
  3. The workflow must be of type "CONVERSATION" and have "ACTIVE" status

Authentication

All API requests require an API key to be included in the headers:

Authorization: Bearer [access-key]

Endpoint

POST https://convobot.intron.health/voicebot/v1/call

Request Body JSON

Field Type Description Required Options Default
workflow_id String Unique identifier for the conversation workflow to be executed yes
workflow_params Array Array of objects containing phone numbers and workflow variables. Phone number is required for each entry. yes
tts_voice_accent String Accent for the voice used on the call no pidgin, english pidgin
tts_voice_gender String Gender of the voice used on the call no male | female female

Basic request and response sample

                    
                        curl -X POST "https://convobot.intron.health/voicebot/v1/call" \
                        -H "Authorization: Bearer your_access_key_here" \
                        -H "Content-Type: application/json" \
                        -d '{
                            "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
                            "workflow_params": [
                                {
                                    "name": "John Doe",
                                    "phone_number": "+1234567890"
                                }
                            ],
                            "tts_voice_accent": "pidgin",
                            "tts_voice_gender": "female"
                        }'
                    
                
                    
                        import requests

                        url = "https://convobot.intron.health/voicebot/v1/call"

                        payload = {
                            "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
                            "workflow_params": [
                                {
                                    "name": "John Doe",
                                    "phone_number": "+1234567890"
                                }
                            ],
                            "tts_voice_accent": "pidgin",
                            "tts_voice_gender": "female"
                        }
                        headers = {
                            "Authorization": "Bearer your_access_key_here"
                        }

                        response = requests.request("POST", url, headers=headers, json=payload)

                        print(response.json)
                    
                
                    
                        const requestOptions = {
                            method: "POST",
                            headers: {
                                'Authorization': 'Bearer your_access_key_here'
                            },
                            body: JSON.stringify(
                                {
                                    "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
                                    "workflow_params": [
                                        {
                                            "name": "John Doe",
                                            "phone_number": "+1234567890"
                                        }
                                    ],
                                    "tts_voice_accent": "pidgin",
                                    "tts_voice_gender": "female"
                                }
                            )
                        };
                            
                        fetch("https://convobot.intron.health/voicebot/v1/call", requestOptions)
                        .then((response) => response.text())
                        .then((result) => console.log(result))
                        .catch((error) => console.error(error));
                    
                
                    
                        {
                            "status": "success",
                            "message": "batch request created successfully",
                            "data": {
                                "batch_id": "660e8400-e29b-41d4-a716-446655440001"
                            }
                        }

Workflow Message Requirements

  • The workflow must be of type "CONVERSATION" and have "ACTIVE" status
  • Use double curly braces syntax to insert dynamic values in your message template
  • Example: "Hello , your appointment is scheduled for at "
  • The endpoint creates a batch record for processing multiple conversation requests

Quotas and Limits

  • Rate limit: 5 requests per second
  • Workflow must be of type "CONVERSATION" (not "ROBOCALL")
  • Workflow status must be "ACTIVE"