History
Introduction
API Category
Making API Requests
Region APIs
Instance APIs
Cloud Hosting Cluster APIs
Image APIs
Instance Launch Template APIs
Placement Group APIs
Key APIs
Security Group APIs
Network APIs
Data Types
Error Codes
Domain name for API request: ccc.intl.tencentcloudapi.com.
This API is used to call the AI model directly to trigger a single outbound call. It supports configuring the model, prompt content, voice, and all call elements through API parameters.
The feature requires purchase of the Intelligent Agent call package and is only available for own telephone numbers. For details, refer to the Intelligent Agent Call Purchase Guide (https://www.tencentcloud.comom/document/product/679/125953?from_cn_redirect=1).
A maximum of 20 requests can be initiated per second for this API.
The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.
| Parameter Name | Required | Type | Description |
|---|---|---|---|
| Action | Yes | String | Common Params. The value used for this API: CreateAICall. |
| Version | Yes | String | Common Params. The value used for this API: 2020-02-10. |
| Region | No | String | Common Params. This parameter is not required. |
| SdkAppId | Yes | Integer | Application ID (required) can be found at https://console.tencentcloud.com/ccc. |
| Callee | Yes | String | Called number. |
| LLMType | Yes | String | Model API protocol type. currently compatible with four protocol types:. -OpenAI protocol (including GPT, hunyuan, DeepSeek, etc.): "OpenAI". -Azure protocol: "azure". -Specifies the "Minimax" protocol. -Dify protocol: "dify". |
| APIKey | Yes | String | Model API key, for authentication information, please refer to the respective model's official website - OpenAI protocol: GPT, DeepSeek; - Azure protocol: Azure GPT; - Minimax:Minimax |
| APIUrl | Yes | String | Model interface address - OpenAI protocol GPT:"https://api.openai.com/v1/" Deepseek:"https://api.deepseek.com/v1" - Azure protocol "https://{your-resource-name}.openai.azure.com?api-version={api-version}" - Minimax protocol "https://api.minimax.chat/v1" |
| SystemPrompt | No | String | ## Identity You are Kate from the appointment department at Retell Health calling Cindy over the phone to prepare for the annual checkup coming up. You are a pleasant and friendly receptionist caring deeply for the user. You don't provide medical advice but would use the medical knowledge to understand user responses. ## Style Guardrails Be Concise: Respond succinctly, addressing one topic at most. Embrace Variety: Use diverse language and rephrasing to enhance clarity without repeating content. Be Conversational: Use everyday language, making the chat feel like talking to a friend. Be Proactive: Lead the conversation, often wrapping up with a question or next-step suggestion. Avoid multiple questions in a single response. Get clarity: If the user only partially answers a question, or if the answer is unclear, keep asking to get clarity. Use a colloquial way of referring to the date (like Friday, January 14th, or Tuesday, January 12th, 2024 at 8am). ## Response Guideline Adapt and Guess: Try to understand transcripts that may contain transcription errors. Avoid mentioning "transcription error" in the response. Stay in Character: Keep conversations within your role's scope, guiding them back creatively without repeating. Ensure Fluid Dialogue: Respond in a role-appropriate, direct manner to maintain a smooth conversation flow. ## Task You will follow the steps below, do not skip steps, and only ask up to one question in response. If at any time the user showed anger or wanted a human agent, call transfer_call to transfer to a human representative. 1. Begin with a self-introduction and verify if callee is Cindy. - if callee is not Cindy, call end_call to hang up, say sorry for the confusion when hanging up. - if Cindy is not available, call end_call politely to hang up, say you will call back later when hanging up. 2. Inform Cindy she has an annual body check coming up on April 4th, 2024 at 10am PDT. Check if Cindy is available. - If not, tell Cindy to reschedule online and jump to step 5. 3. Ask Cindy if there's anything that the doctor should know before the annual checkup. - Ask followup questions as needed to assess the severity of the issue, and understand how it has progressed. 4. Tell Cindy to not eat or drink that day before the checkup. Also tell Cindy to give you a callback if there's any changes in health condition. 5. Ask Cindy if she has any questions, and if so, answer them until there are no questions. - If user asks something you do not know, let them know you don't have the answer. Ask them if they have any other questions. - If user do not have any questions, call function call_end to hang up. |
| Model | No | String | Model name, such as - OpenAI protocol "gpt-4o-mini","gpt-4o","deepseek-chat"; - Azure protocol "gpt-4o-mini", "gpt-4o"; - Minimax protocol "deepseek-chat". |
| VoiceType | No | String | The following voice parameter values are available by default. If you wish to customize the voice type, please leave VoiceType blank and configure it in the CustomTTSConfig parameter. Chinese: ZhiMei: Zhimei, customer service female voice ZhiXi: Zhixi, general female voice ZhiQi: Zhiqi, customer service female voice ZhiTian: Zhitian, female child voice AiXiaoJing: Ai Xiaojing, dialogue female voice English: WeRose:English Female Voice Monika:English Female Voice Japanese: Nanami Korean: SunHi Indonesian (Indonesia): Gadis Malay (Malaysia): Yasmin Tamil (Malaysia): Kani Thai (Thailand): Achara Vietnamese (Vietnam): HoaiMy |
| Callers.N | No | Array of String | Caller number list |
| WelcomeMessage | No | String | Used to set the AI Agent Welcome Message. |
| WelcomeType | No | Integer | 0: Use welcomeMessage (if empty, the callee speaks first; if not empty, the bot speaks first) 1: Use AI to automatically generate welcomeMessage and speak first based on the prompt |
| WelcomeMessagePriority | No | Integer | 0: interruptible by default, 2: high priority non-interruptible. |
| MaxDuration | No | Integer | Maximum Waiting Duration (milliseconds), default is 60 seconds, if the user does not speak within this time, the call is automatically terminated |
| Languages.N | No | Array of String | ASR Supported Languages, default is "zh" Chinese, Fill in the array with up to 4 languages, the first is the primary language for recognition, followed by optional languages, Note: When the primary language is a Chinese dialect, optional languages are invalid Currently, the supported languages are as follows. The English name of the language is on the left side of the equals sign, and the value to be filled in the Language field is on the right side, following ISO639: 1. Chinese = "zh" # Chinese 2. Chinese_TW = "zh-TW" # Taiwan (China) 3. Chinese_DIALECT = "zh-dialect" # Chinese Dialect 4. English = "en" # English 5. Vietnamese = "vi" # Vietnamese 6. Japanese = "ja" # Japanese 7. Korean = "ko" # Korean 8. Indonesia = "id" # Indonesian 9. Thai = "th" # Thai 10. Portuguese = "pt" # Portuguese 11. Turkish = "tr" # Turkish 12. Arabic = "ar" # Arabic 13. Spanish = "es" # Spanish 14. Hindi = "hi" # Hindi 15. French = "fr" # French 16. Malay = "ms" # Malay 17. Filipino = "fil" # Filipino 18. German = "de" # German 19. Italian = "it" # Italian 20. Russian = "ru" # Russian |
| InterruptMode | No | Integer | Interrupt ai speaking mode. default is 0. 0 indicates automatic interruption and 1 indicates no interruption. |
| InterruptSpeechDuration | No | Integer | Used when InterruptMode is 0, unit in milliseconds, default is 500ms. It means that the server-side detects ongoing vocal input for the InterruptSpeechDuration milliseconds and then interrupts. |
| EndFunctionEnable | No | Boolean | Whether the model supports (or enables) call_end function calling |
| EndFunctionDesc | No | String | Effective when EndFunctionEnable is true; the description of call_end function calling, default is "End the call when user has to leave (like says bye) or you are instructed to do so." |
| TransferFunctionEnable | No | Boolean | Whether the model supports (or enables) transfer_to_human function calling. |
| TransferItems.N | No | Array of AITransferItem | Takes effect when transferfunctionenable is true: transfer to human configuration. |
| NotifyDuration | No | Integer | The duration after which the user hasn't spoken to trigger a notification, minimum 10 seconds, default 10 seconds |
| NotifyMessage | No | String | The AI prompt when NotifyDuration has passed without the user speaking, default is "Sorry, I didn't hear you clearly. Can you repeat that?" |
| NotifyMaxCount | No | Integer | Maximum number of times to trigger ai prompt sound, unlimited by default. |
| CustomTTSConfig | No | String | Either the VoiceType field or a custom TTS is required. this uses your own custom TTS, while VoiceType provides some built-in voice types.
Configure the timbre type. see volcano TTS documentation link
For the specific protocol specification, refer to tencent documentation |
| VadSilenceTime | No | Integer | Automatic speech recognition vad time ranges from 240 to 2000, with a default of 1000, measured in milliseconds. smaller values will make automatic speech recognition segment faster. |
| ExtractConfig.N | No | Array of AICallExtractConfigElement | Call content extraction configuration. |
| Temperature | No | Float | Model temperature control. |
| Variables.N | No | Array of Variable | Common variable: prompt content variable welcome message variable welcome message delay playback (in seconds): welcome-message-delay dify variable .dify-inputs-xxx specifies the inputs variable for dify. 2. the dify-inputs-user specifies the user value for dify. 3. dify-inputs-conversation_id is the conversation_id value of dify. |
| TopP | No | Float | Specifies the model topP. |
| VadLevel | No | Integer | The vad far-field voice suppression capacity (does not impact asr recognition performance). value range: [0, 3]. default is 0. recommended setting: 2 for better far-field voice suppression. |
| ToneWord | No | ToneWordInfo | Transition. |
| EnableComplianceAudio | No | Boolean | Compliant prompt sound. This parameter set to true (default) means call initiation plays morse code, with a Note that the conversation content is AI-generated. Passing 'false' to this parameter disables the compliance prompt sound. passing 'false' signifies you have read and agree to the following agreement:. Our side fully acknowledges and understands that according to the laws and regulations specified in the "cybersecurity law" (https://www.cac.gov.cn/2016-11/07/c_1119867116.htm), "provision on administration of deep synthesis of internet-based information service" (https://www.gov.cn/zhengce/zhengceku/2022-12/12/content_5731431.htm), "interim measures for the management of generative artificial intelligence services" (https://www.gov.cn/zhengce/zhengceku/202307/content_6891752.htm), and "measures for the identification of artificial intelligence-generated synthetic content" (https://www.gov.cn/zhengce/zhengceku/202503/content_7014286.htm), explicit and implicit identification should be added to ai-generated synthetic content. based on business requirements, we request tencent cloud not to add explicit identification to generated synthetic content. we commit to lawful and compliant use of generated synthetic content to avoid causing confusion or misunderstanding. if the generated synthetic content is used to provide services to the public or spread over networks, we will proactively add explicit identification that complies with legal provisions and national standards, and bear the legal obligation for identifying ai-generated synthetic content. our side will fully assume all related responsibilities if adverse consequences arise from failure to appropriately and reasonably fulfill the obligation of ai content identification, or if penalties are imposed by the competent department. |
| EnableVoicemailDetection | No | Boolean | Whether to enable voice mail recognition. |
| VoicemailAction | No | Integer | Detect behavior when the peer is voice mail. this parameter is valid only when EnableVoicemailDetection is True. 0: hang up the phone (default). |
| LLMExtraBody | No | String | Large model extended parameter, format is json string. |
| MaxCallDurationMs | No | Integer | Maximum call duration, default not limited. unit: milliseconds (ms). |
| MaxRingTimeoutSecond | No | Integer | Maximum ringing duration. auto hang up when the duration threshold is reached. only own number supports current parameter.. |
| AmbientSoundType | No | String | Ambient sound scenario. if so, leave it blank. Coffee_shops: chat in the coffee shop communication environment with background. busy_office: customer service center. |
| AmbientSoundVolume | No | Float | Ambient sound volume. if AmbientSoundType is empty, this field is left blank. value ranges from [0,2]. the lower the value, the softer the ambient sound; the higher the value, the louder the ambient sound. if not set, use the default value 1. |
| Parameter Name | Type | Description |
|---|---|---|
| SessionId | String | Newly created session ID. |
| RequestId | String | The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem. |
This example simulates a hospital using a large model to conduct telephone follow-up surveys with the parents of patients discharged from surgery.
POST / HTTP/1.1
Host: ccc.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateAICall
<Common request parameters>
{
"Callee": "008612300000000",
"SdkAppId": 1400000000,
"SystemPrompt": "You are Dr. Li, a friendly and kind follow-up doctor at the People's Hospital, making a phone call to the parent of patient Xiao Ming."
"WelcomeMessage": "Hello"
"LLMType": "openai",
"Model": "gpt-4o-mini",
"APIKey": "sk-proj-xxxxx",
"APIUrl": "https://api.openai.com/v1/",
"VoiceType": "ZhiXi",
"EndFunctionEnable": true
}
{
"Response": {
"RequestId": "6bb56a09-2787-40bc-80c5-dc6dab783eff",
"SessionId": "6bb56a09278740bc80c5dc6dab783eff"
}
}
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.
The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.
| Error Code | Description |
|---|---|
| FailedOperation.CallOutFailed | Outbound call failure. |
| FailedOperation.CalleeIsBlackUser | High-risk users, do not call |
| FailedOperation.CallerOverFrequency | Caller ID exceeds the outbound call limit. |
| FailedOperation.CalloutRuleBlindArea | The number is in a restricted calling zone. |
| FailedOperation.CalloutRuleMaxCallCountCalleeIntervalTime | Exceeded call limit for the callee within a set time. |
| FailedOperation.CalloutRuleMaxCallCountCalleePerDayAppID | Exceeded daily call limit for the callee. |
| FailedOperation.CalloutRuleNotWorkTime | Calls are not allowed at this time. |
| FailedOperation.NoCallOutNumber | No available outbound call numbers. |
| FailedOperation.PermissionDenied | Insufficient permissions. |
| InternalError | An internal error occurs. |
| InvalidParameterValue | Invalid Parameter |
| InvalidParameterValue.InstanceNotExist | The SDKAppID does not exist. |
| LimitExceeded.BasePackageExpired | Your call package is used up. |
Esta página foi útil?
Você também pode entrar em contato com a Equipe de vendas ou Enviar um tíquete em caso de ajuda.
comentários