发送呼叫

开发环境

POST

/v1/calls

发送包含自定义目标和操作的 AI 电话。

请求示例

Shell

JavaScript

Java

Swift

curl --location --request POST 'http://dev-cn.your-api-server.com/v1/calls' \
--header 'authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "phone_number": "<string>",
  "task": "<string>",
  "pathway_id": "<string>",
  "voice": "<string>",
  "first_sentence": "<string>",
  "wait_for_greeting": true,
  "interruption_threshold": 123,
  "model": "<string>",
  "temperature": 123,
  "keywords": [
    "<string>"
  ],
  "pronunciation_guide": [
    {}
  ],
  "transfer_phone_number": "<string>",
  "transfer_list": {},
  "language": "<string>",
  "timezone": "<string>",
  "request_data": {},
  "tools": [
    {}
  ],
  "dynamic_data": [
    {
      "dynamic_data[i].response_data": [
        {}
      ]
    }
  ],
  "start_time": "<string>",
  "voicemail_message": "<string>",
  "voicemail_action": {},
  "max_duration": 123,
  "record": true,
  "from": "<string>",
  "webhook": "<string>",
  "metadata": {},
  "analysis_schema": {},
  "answered_by_enabled": true
}'

响应示例

{
  "status": "success",
  "message": "Call successfully queued.",
  "call_id": "9d404c1b-6a23-4426-953a-a52c392ff8f1",
  "batch_id": null
}

请求参数

Header 参数

Content-Type

string

必需

示例值:

application/json

authorization

string

必需

示例值:

Body 参数application/json

phone_number

string

必需

要拨打的电话号码。+1如果未指定，国家/地区代码默认为（美国）。为获得最佳结果，请使用E.164格式。

task

string

可选

提供理想对话流程的说明、相关信息和示例。这是您的提示，您告诉代理要做什么。建议： - 包括代理的上下文和背景/角色，例如"You are {name}, a customer service agent at {company} calling {name} about {reason}。 - 措辞说明就像您在通话前与客服人员交谈一样。 - 每当您告诉客服人员不要做某事时，请提供一个他们应该做什么的示例。 - 尽可能将提示字符控制在 2,000 个字符以内。 - 想要轻松测试您的代理的具体行为方式吗？尝试代理测试！

pathway_id

string

可选

这是您在我们的开发门户上创建的路径的路径 ID。您可以通过点击此处路径的“复制 ID”按钮来访问您的路径 ID 注意：某些参数在使用路径时不适用。

voice

string

可选

要使用的 AI 代理的声音。接受任何形式的语音 ID，包括自定义语音克隆和语音预设。默认语音可以直接通过其名称而不是 ID 来引用。使用示例：voice: "maya" 平淡的策划声音： maya mason ryan adriana tina matt evelyn 使用GET /v1/voices端点查看可用语音的完整列表。

first_sentence

string

可选

让您的客服人员为其第一响应说出特定的短语或句子。

wait_for_greeting

boolean

可选

默认情况下，客服人员在呼叫接通后立即开始通话。当wait_for_greeting设置为时true，座席将等待呼叫接收者先发言然后再响应。

interruption_threshold

integer

可选

调整 AI 在等待用户说完时的耐心程度。较低的值意味着 AI 会更快地响应，而较高的值意味着 AI 在响应之前会等待更长时间。推荐范围：50-200 50：极其快速的来回对话 100：平衡地以自然的速度做出反应 200：非常有耐心，允许长时间停顿和中断。非常适合收集详细信息。尝试从 100 开始，然后根据您的用例需要以 ~10 的增量进行小幅调整。

model

string

可选

选择用于您通话的型号。选项：gpt4、base、turbo和enhanced。几乎在所有情况下，enhanced都是最佳选择。

temperature

integer

可选

0 到 1 之间的值，控制 LLM 的随机性。 0 将导致更多确定性输出，而 1 将导致更多随机性。

keywords

array[string]

可选

这些单词将在转录引擎中得到增强 - 建议用于专有名词或经常被错误转录的单词。例如，如果“Reece”一词经常被转录为“Reese”等同音异义词，您可以这样做： { "keywords": ["Reece"] } 为了获得更强的关键字增强效果，您可以在单词后面放置一个冒号，然后放置一个增强因子。默认提升因子为 2。 Copy { "keywords": ["Reece:3"] }

pronunciation_guide

array [object]

可选

发音指南是指导代理如何说出特定单词的指南array。objects这对于术语或名称复杂的情况非常有用。

transfer_phone_number

string

可选

代理可以在特定条件下转接的电话号码 - 例如被要求与人员或主管通话。

transfer_list

object

可选

让您的代理能够将呼叫转接至一组电话号码。 transfer_phone_number如果指定了 a 则覆盖transfer_list.default。默认为transfer_list.default, 或所选的电话号码。将呼叫路由到不同部门的示例用法： "transfer_list": { "default": "+12223334444", "sales": "+12223334444", "support": "+12223334444", "billing": "+12223334444" }

language

string

可选

选择您选择的支持语言。针对该语言优化 API 的每个部分 - 转录、语音和其他内部工作。支持的语言及其代码：英语：ENG 西班牙语：ESP 法语： FRE 抛光：POL 德语：GER 意大利语：ITA 巴西葡萄牙语：PBR 葡萄牙语：POR

timezone

string

可选

设置通话的时区。自动处理美国境内的呼叫。这对于依赖预约设置、日程安排或根据一天中的时间进行不同行为的用例有很大帮助。时区选项位于TZ 标识符列中。

request_data

object

可选

您在此处输入的任何 JSON 都将在呼叫期间对 AI 代理可见 - 并且也可以通过提示变量进行引用。例如，假设您希望在您的应用程序中以编程方式设置您正在呼叫的人的姓名。您可以设置request_data为： { "phone_number": "+1...", "task": "...", "first_sentence": "Hello {{name}}! How are you doing today?", // also works in the prompt, tools, etc. "request_data": { "name": "John Doe", } } 有关提示变量如何工作的更多信息，请查看自定义工具教程。

tools

array [object]

可选

通过API调用与现实世界交互。详细教程在这里：自定义工具

dynamic_data

array [object {1}]

可选

向外部 API 发出动态请求并在 AI 响应中使用数据。

dynamic_data[i].response_data

array [object]

可选

start_time

string

可选

您希望通话开始的时间。如果您未指定时间（或者该时间是过去的时间），则呼叫将立即发送。按照格式设置您的时间YYYY-MM-DD HH:MM:SS -HH:MM（例如2021-01-01 12:00:00 -05:00）。时区是可选的，如果未指定，则默认为 UTC。注意：可以使用POST /v1/calls/:call_id/stop端点取消计划的呼叫。

voicemail_message

string

可选

当AI遇到语音邮件时，它会在嘟嘟声后留下此消息，然后立即结束通话。警告：如果amd设置为true或voicemail_action设置为ignore，则这仍然适用于语音邮件，但不会挂断 IVR 系统。

voicemail_action

object

可选

这是与人工智能的决策分开处理的，并且会覆盖它。选项： - hangup - leave_message - ignore 例子： - 通过语音邮件应答呼叫（特别是发出蜂鸣声或提示音）： - 如果voicemail_message设置，则将留下该消息，然后通话将结束。 - 否则，通话立即结束（不管amd） - 呼叫由 IVR 系统或电话树应答： - 如果amd设置为true，AI 将导航系统并正常继续。 - 如果voicemail_action设置为ignore，AI 将忽略 IVR 并正常继续。 - 否则，如果voicemail_message设置了，它将留下该消息并结束通话。 - 最后，如果这些条件都不满足，通话将立即结束。注意：如果voicemail_message设置了，则无论 .AI 是否存在，AI 都会留言voicemail_action。

max_duration

integer

可选

当通话开始时，会设置一个max_duration分钟计时器。在该计时器结束时，如果呼叫仍然处于活动状态，它将自动结束。

record

boolean

可选

要记录您的电话通话，请设置record为 true。呼叫完成后，您可以通过recording_url呼叫详细信息或 Webhook 中的字段进行访问。

from

string

可选

指定您拥有的或从您的 Twilio 帐户上传的电话号码。国家/地区代码为必填项，必须排除空格或括号。默认情况下，呼叫是从 Bland 拥有的单独号码池发起的。

webhook

string

必需

通话结束后，我们会将 POST 请求中的通话详细信息发送到您在此处指定的 URL。请求正文将与GET /v1/calls/:call_id端点的响应匹配。

metadata

object

可选

添加您想要与呼叫关联的任何其他信息。这对于跟踪或分类呼叫非常有用。您在此处放置的任何内容都将返回到您的 webhook 或下的调用详细信息中metadata。例子： "metadata": { "campaign_id": "1234", "source": "web" }

analysis_schema

object

可选

当通话结束时，人工智能将分析通话记录和通话详细信息。定义一个 JSON 架构，决定如何获取有关呼叫的信息 - 电子邮件地址、姓名、预约时间或任何其他类型的自定义数据等信息。在 Webhook 响应中或以后每当您检索调用数据时，您都会在下获得您定义的数据analysis。例如，如果您想从调用中检索此信息：

json "analysis_schema": {   "email_address": "email",   "first_name": "string",   "last_name": "string",   "wants_to_book_appointment": "boolean",   "appointment_time": "YYYY-MM-DD HH:MM:SS" }

调用完成后，您将在 Webhook 中填写如下内容：

json "analysis": {   "email_address": "johndoe@gmail.com",   "first_name": "John",   "last_name": "Doe",   "wants_to_book_appointment": true,   "appointment_time": "2024-01-01 12:00:00" }

answered_by_enabled

boolean

可选

如果将此设置为 true，我们会从呼叫开始时处理音频，以确定是由人工应答还是由语音邮件应答。在呼叫详细信息或 Webhook 响应中，您将看到answered_by带有值human、unknown或的字段voicemail。准确性注意事项： - 当answered_by是voicemail或时human，几乎 100% 准确。 - 如果是这样unknown，请尝试通过添加answered_by到您的analysis_schema.

示例

返回响应

🟢200成功

application/json

Body

status

string

必需

可以是success或error.

message

string

必需

解释呼叫状态的消息。

call_id

string

必需

呼叫的唯一标识符（仅当状态为时才出现success）。

batch_id

null

必需

调用的批次 ID（仅当状态为时才显示success）。

修改于 2024-05-10 06:52:34

使用 Pathways 发送呼叫（简单）

使用 AI 分析通话