Skip to content

wa calling

Jump to bottom
GiuFLim edited this page Sep 19, 2025 · 13 revisions

wa calling

功能接口

此API包含4个接口：

  • 启用商户号码的calling能力 /api/wa/calling/enable
  • 禁用商户号码的calling能力 /api/wa/calling/disable
  • 查询商户号码的calling能力 /api/wa/calling/get
  • 查询calling的流水记录 /api/wa/calling/query

鉴权机制

鉴权规则请参考地址：API接口调用约定

请求参数

header参数：

参数名 类型 必选 示例值 说明
accessKey String 是 fme2na3kdi3ki 用户身份标识
ts String 是 1655710885431 当前请求的时间戳（单位是毫秒），牛信服务端允许用户端请求最大时间误差为60秒
bizType String 是 2 WhatsApp业务类型，取固定值“2”
action String 是 mt WhatsApp业务操作，取固定值“mt”
sign String 是 6e9506557d1f289501d333ee2c365826 API入参参数签名，签名算法

启用商户号码的calling能力

使用此接口启用商户号码的calling能力。

接口

  • URL：https://api2.nxcloud.com/api/wa/calling/enable
  • Method：POST
  • Content-Type：application/json
  • 需要鉴权：是

body参数：

参数名 类型 必选 示例值 说明
appkey String 是 pem28kje 应用appkey
business_phone String 是 86133xxx 商户的WhatsApp号码，需要带国码。如86158xxxx1795
icon_status Integer 是 1 是否显示通话图标 1=显示 0=隐藏
permission_status Integer 是 1 是否提示呼叫权限请求 1启用, 0禁用
recording_status Integer 是 0 是否启用录音 1启用, 0禁用
hours_status Integer 是 0 是否定制业务时间 1启用 0禁用
hours_customize Object 否 定制业务时间 hours_status=1的情况下 必须有值，结构如下
sip_servers String 是 4.4.4.4:8080 SIP servers信息 ip:端口 多个通过逗号分隔

hours_customize Object

定制业务时间 hours_status=1的情况下 必须有值，结构如下

参数名 类型 必选 示例值 说明
status String 是 ENABLED 固定值 ENABLED(启用) DISABLED(禁用)
timezone_id String 是 Etc/GMT-8 meta文档中支持的时区
weekly_operating_hours Array[Object] 是 自定义周一至周日可接听时间段
holiday_schedule Array[Object] 否 自定义假期不可接听时间段

weekly_operating_hours Array[Object]

自定义周一至周日可接听时间段

  • Maximum of 2 entries allowed per day of week
  • open_time must be before close_time
  • Overlapping entries not allowed
参数名 类型 必选 示例值 说明
day_of_week String 是 MONDAY The day of the week. Can take one of seven values: "MONDAY", “TUESDAY”, “WEDNESDAY”, “THURSDAY”, “FRIDAY”, “SATURDAY”, “SUNDAY”
open_time String 是 0400 Times represented in 24 hour format, e.g. ”1130” = 11:30AM
close_time String 是 1020 Times represented in 24 hour format, e.g. ”1130” = 11:30AM

holiday_schedule Array[Object]

自定义假期不可接听时间段

An optional override to the weekly schedule.

Up to 20 overrides can be specified.

Note: If holiday_schedule is not passed in the request, then the existing holiday_schedule will be deleted and replaced with an empty schedule.

参数名 类型 必选 示例值 说明
date String 是 2025-02-10 Date for which you want to specify the override.YYYY-MM-DD format.
start_time String 是 0400 Times represented in 24 hour format, e.g. ”1130” = 11:30AM
end_time String 是 1020 Times represented in 24 hour format, e.g. ”1130” = 11:30AM

请求示例1

{
    "appkey": "xxx",
    "business_phone": "xxx",
    "icon_status": 1,
    "hours_status": 0,
    "permission_status": 0,
    "recording_status": 1,
    "sip_servers": "4.4.4.4:5060"
}

请求示例2 定制业务时间

{
    "appkey": "XXX",
    "business_phone": "XXX",
    "icon_status": 1,
    "hours_status": 1,
    "hours_customize": {
        "status": "ENABLED",
        "timezone_id": "Etc/GMT-8",
        "weekly_operating_hours": [
            {
                "day_of_week": "MONDAY",
                "open_time": "0400",
                "close_time": "1020"
            },
            {
                "day_of_week": "TUESDAY",
                "open_time": "0108",
                "close_time": "1020"
            },
            {
                "day_of_week": "THURSDAY",
                "open_time": "0108",
                "close_time": "1020"
            }
        ],
        "holiday_schedule": [
            {
                "date": "2025-10-01",
                "start_time": "0000",
                "end_time": "0259"
            },
            {
                "date": "2025-10-02",
                "start_time": "0400",
                "end_time": "0559"
            },
            {
                "date": "2025-10-03",
                "start_time": "0800",
                "end_time": "1759"
            },
            {
                "date": "2025-10-04",
                "start_time": "2000",
                "end_time": "2359"
            }
        ]
    },
    "permission_status": 1,
    "recording_status": 1,
    "sip_servers": "4.4.4.4:5060"
}

响应参数

参数名 类型 示例值 说明
code String 0
message String Success
data Object

data Object

参数名 类型 示例值 说明
sips Array[Object] nx sip对接信息

sips Array[Object]

参数名 类型 示例值 说明
sip_ip String sip ip
outbound String outbound
inbound String inbound

响应示例1

{
    "code": 0,
    "message": "Success",
    "data": {
        "sips": [
            {
                "sip_ip": "34.92.233.134",
                "outbound": "34.92.233.134:6030",
                "inbound": "34.92.233.134:3080"
            }
        ],
        "business_phone": "xxx"
    },
    "traceId": "da42a443e13c4ce39bf14728180cd4cb"
}

响应示例2

{
    "code": 10015,
    "message": "permission_status not in (0, 1)",
    "traceId": "33904fce3e5744e8bc842906967c202b"
}

响应示例3

{
    "code": 10012,
    "message": "Wa calling setting fail (#10) Business initiated calls are not supported for the phone number country. Disable callback permission status if you want to enable only user initiated calls",
    "traceId": "2527e891748e4ff694e700a4aed6f2fe"
}

禁用商户号码的calling能力

使用此接口启用禁用号码的calling能力。

接口

  • URL：https://api2.nxcloud.com/api/wa/calling/disable
  • Method：POST
  • Content-Type：application/json
  • 需要鉴权：是

body参数：

参数名 类型 必选 示例值 说明
appkey String 是 pem28kje 应用appkey
business_phone String 是 86133xxx 商户的WhatsApp号码，需要带国码。如86158xxxx1795

请求示例1

{
    "appkey": "xxx",
    "business_phone": "xxx"
}

响应参数

参数名 类型 示例值 说明
code String 0
message String Success
data Object

data Object

参数名 类型 示例值 说明
disabled Boolean true true禁用成功/ false禁用失败
business_phone String 商户号

响应示例1

{
    "code": 0,
    "message": "Success",
    "data": {
        "disabled": true,
        "business_phone": "xxx"
    },
    "traceId": "97176a1d20494c9380c218b202d56282"
}

响应示例1

{
    "code": 10003,
    "message": "WhatsApp business phone is not bind app",
    "traceId": "dfc3f3a9be3d4b089aadf5e8374c0a9b"
}

查询商户号码的calling能力

使用此接口查询商户号码的calling能力。

接口

  • URL：https://api2.nxcloud.com/api/wa/calling/get
  • Method：POST
  • Content-Type：application/json
  • 需要鉴权：是

body参数：

参数名 类型 必选 示例值 说明
appkey String 是 pem28kje 应用appkey
business_phone String 是 86133xxx 商户的WhatsApp号码，需要带国码。如86158xxxx1795

请求示例1

{
    "appkey": "xxx",
    "business_phone": "xxx"
}

响应参数

参数名 类型 示例值 说明
code String 0
message String Success
data Object

data Object

参数名 类型 示例值 说明
status Integer 1 0=calling能力禁用 1=calling能力启用 2=欠费中
business_phone String 86133xxx 商户的WhatsApp号码，需要带国码。如86158xxxx1795
icon_status Integer 1 是否显示通话图标 1=显示 0=隐藏
permission_status Integer 1 是否提示呼叫权限请求 1启用, 0禁用
recording_status Integer 0 是否启用录音 1启用, 0禁用
hours_status Integer 0 是否定制业务时间 1启用 0禁用
hours_customize Object 定制业务时间
sip_servers String 4.4.4.4:8080 SIP servers信息 ip:端口 多个通过逗号分隔
sips Array[Object] nx sip对接信息

sips Array[Object]

参数名 类型 示例值 说明
sip_ip String sip ip
outbound String outbound
inbound Object inbound

响应结果1

{
    "code": 0,
    "message": "Success",
    "data": {
        "sips": null,
        "status": 0,
        "business_phone": "xxx",
        "icon_status": null,
        "hours_status": null,
        "hours_customize": null,
        "permission_status": null,
        "recording_status": null,
        "sip_servers": null
    },
    "traceId": "c05f8a2664e3484480e452b279d88d96"
}

响应结果2

{
    "code": 0,
    "message": "Success",
    "data": {
        "sips": [
            {
                "sip_ip": "34.92.233.134",
                "outbound": "34.92.233.134:6030",
                "inbound": "34.92.233.134:3080"
            }
        ],
        "status": 1,
        "business_phone": "xxx",
        "icon_status": 1,
        "hours_status": 0,
        "hours_customize": null,
        "permission_status": 0,
        "recording_status": 1,
        "sip_servers": "47.237.28.169:5060"
    },
    "traceId": "6ec91c2f05cd4e50b021594e98b31c32"
}

响应结构3

{
    "code": 0,
    "message": "Success",
    "data": {
        "sips": [
            {
                "sip_ip": "34.92.233.134",
                "outbound": "34.92.233.134:6030",
                "inbound": "34.92.233.134:3080"
            }
        ],
        "status": 1,
        "business_phone": "xxx",
        "icon_status": 1,
        "hours_status": 1,
        "hours_customize": "{\"status\":\"ENABLED\",\"timezone_id\":\"Etc/GMT-8\",\"weekly_operating_hours\":[{\"day_of_week\":\"MONDAY\",\"open_time\":\"0400\",\"close_time\":\"1020\"},{\"day_of_week\":\"TUESDAY\",\"open_time\":\"0108\",\"close_time\":\"1020\"},{\"day_of_week\":\"THURSDAY\",\"open_time\":\"0108\",\"close_time\":\"1020\"}],\"holiday_schedule\":[{\"date\":\"2025-10-01\",\"start_time\":\"0000\",\"end_time\":\"0259\"},{\"date\":\"2025-10-01\",\"start_time\":\"0400\",\"end_time\":\"0559\"},{\"date\":\"2025-10-01\",\"start_time\":\"0800\",\"end_time\":\"1759\"},{\"date\":\"2025-10-01\",\"start_time\":\"2000\",\"end_time\":\"2359\"}]}",
        "permission_status": 0,
        "recording_status": 1,
        "sip_servers": "47.237.28.169:5060"
    },
    "traceId": "4b46b48f4e4d4d49b2a171c128d69ed7"
}

查询calling的流水记录

使用此接口查询calling的流水记录。

接口

body参数：

参数名 类型 必选 示例值 说明
appkey String 是 pem28kje 应用appkey
business_phone String 是 86133xxx 商户的WhatsApp号码，需要带国码。如86158xxxx1795
call_id String 是 call_id

请求示例1

{
    "appkey": "xxx",
    "business_phone": "xxx",
    "call_id": "outgoing:wacid.HBgNODYxMzc2MzMzOTA3MBUCABIYIDAyQ0JGREQyNkM1Qjg0ODI3NTU3Q0JBOEYwRUZEM0I3HBgMNjIyMTUwOTgwMzY2FQIAFTgA"
}

响应参数

参数名 类型 示例值 说明
code String 0
message String Success
data Object

data Object

参数名 类型 示例值 说明
app_id Integer 282 应用id
business_phone String 86133xxx 商户的WhatsApp号码，需要带国码。如86158xxxx1795
wabaId String 1 waba_id
calls Object[Array] calls信息

calls Object[Array]

参数名 类型 示例值 说明
call_id String xxx String
from String xxx 拨打方号码
to String xxx 接听方号码
costs Object 费用信息
start_time String 通话开始时间戳
end_time String 通话终止时间戳
record String 录音文件地址
call_duration Integer 20 通话时长/秒
fee_duration Integer 24 计费时长/秒
bill_type String 6+6 计费方式6+6
end_direction Integer 0 挂断方：0主叫， 1被叫，2服务器,3 未知
end_reason String Busy Here 终止原因

costs object

参数名 类型 示例值 说明
direction Integer 1 1-呼出 0-呼入
currency String USD 币种
price Double 0.33 币种对应的费用

响应结果1

{
    "code": 0,
    "message": "Success",
    "data": {
        "app_id": 282,
        "business_phone": "xxx",
        "wabaId": "xxx",
        "calls": [
            {
                "call_id": "outgoing:wacid.HBgNODYxMzc2MzMzOTA3MBUCABIYIDAyQ0JGREQyNkM1Qjg0ODI3NTU3Q0JBOEYwRUZEM0I3HBgMNjIyMTUwOTgwMzY2FQIAFTgA",
                "from": "xxx",
                "to": "xxx",
                "costs": [
                    {
                        "direction": 0,
                        "currency": "EUR",
                        "price": 0.080000
                    }
                ],
                "start_time": "1757915478",
                "end_time": "1757915509",
                "record": "https://hhd.xxx",
                "call_duration": 31,
                "fee_duration": 36,
                "bill_type": "6+6",
                "end_direction": 1,
                "end_reason": "NORMAL_CLEARING"
            }
        ]
    },
    "traceId": "0146fbd1aa46440fac0934bcc8343ca4"
}

响应结果2

{
    "code": 10014,
    "message": "Calling cdr not exist",
    "traceId": "7673af8320764892977efbb25e4077dc"
}

创建通话权限申请-通知模板

components.type = CALL_PERMISSION_REQUEST

创建模板请参照创建模板

{
    "appkey": "xxx",
    "messaging_product": "whatsapp",
    "business_phone": "xxx",
    "category": "MARKETING",
    "name": "sample_calling_done_ok",
    "language": "en_US",
    "components": [
        {
            "format": "TEXT",
            "text": "Please call me  in need",
            "type": "HEADER"
        },
        {
            "text": "We would like to call you to help support your query on Order No: {{1}} and so on",
            "type": "BODY",
            "example": {
                "body_text": [
                    [
                        "ON-12345"
                    ]
                ]
            }
        },
        {
            "text": "Talk to you soon!",
            "type": "FOOTER"
        },
        {
            "type": "CALL_PERMISSION_REQUEST"
        }
    ]
}

发送通话权限申请消息-模板消息

发送消息请参照发送消息

{
    "appkey": "tEHu0Vb1",
    "business_phone": "xxx",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "xxx",
    "type": "template",
    "template": {
        "name": "sample_calling_done_ok",
        "language": {
            "policy": "deterministic",
            "code": "en_US"
        },
        "components": [
            {
                "type": "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "DT00P4kL"
                    }
                ]
            }
        ]
    }
}

发送通话权限申请消息-互动类消息

interactive.type=call_permission_request

interactive.action.name=call_permission_request

发送消息请参照发送消息

{
    "appkey": "xxx",
    "business_phone": "xxx",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "xxx",
    "type": "interactive",
    "interactive": {
        "type": "call_permission_request",
        "action": {
            "name": "call_permission_request"
        },
        "body": {
            "text": "We would like to call you to help support your query on Order No: ON-12853."
        }
    }
}

用户接收通话权限申请反馈

同意/拒绝 上行消息callback结构

消息webhook请参照消息webhook

同意 "response": "accept"

{
    "app_id": "48",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "context": {
                "from": "xxx",
                "id": "wamid.3a5d01a5b5ce49279f3dcb9c3bd6341a",
                "meta_message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYEkM3NUFFOUY4MDQ4Q0NCQUIzNQA="
            },
            "cost": {
                "cdr_type": 1,
                "currency": "USD",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDNBNUNEQjFBQURBRTk4OTY3REE5AA==",
                "price": 0
            },
            "from": "xxx",
            "id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDNBNUNEQjFBQURBRTk4OTY3REE5AA==",
            "interactive": {
                "call_permission_reply": {
                    "expiration_timestamp": 1756452996,
                    "response": "accept",
                    "response_source": "user_action"
                },
                "type": "call_permission_reply"
            },
            "timestamp": "1755848199",
            "type": "interactive"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

拒绝 "response": "reject"

{
    "app_id": "48",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "context": {
                "from": "xxx",
                "id": "wamid.3a5d01a5b5ce49279f3dcb9c3bd6341a",
                "meta_message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYEkM3NUFFOUY4MDQ4Q0NCQUIzNQA="
            },
            "cost": {
                "cdr_type": 1,
                "currency": "USD",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDNBNUNEQjFBQURBRTk4OTY3REE5AA==",
                "price": 0
            },
            "from": "xxx",
            "id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDNBNUNEQjFBQURBRTk4OTY3REE5AA==",
            "interactive": {
                "call_permission_reply": {
                    "expiration_timestamp": 1756452996,
                    "response": "reject",
                    "response_source": "user_action"
                },
                "type": "call_permission_reply"
            },
            "timestamp": "1755848199",
            "type": "interactive"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

calling 通话记录 webhook回执结构参数

webhook详细结构请参照webhook

calls Array[object]

参数名 类型 说明
call_id String call_id
from String 拨打方号码
to String 接听方号码
costs Objects 费用信息
start_time String 通话开始时间戳
end_time String 通话终止时间戳
record String 录音文件地址
call_duration Integer 通话时长
fee_duration Integer 计费时长
bill_type String 计费方式60+60
end_direction Integer 挂断方：0主叫， 1被叫，2服务器,3 未知
end_reason String 终止原因

costs object

参数名 类型 说明
direction Integer 1-呼出 0-呼入
currency String 币种
price Double 币种对应的费用

回执结构示例1

{
    "app_id": 277,
    "business_phone": "xxx",
    "channel": 2,
    "merchant_phone": "xxx",
    "messaging_product": "whatsapp",
    "wabaId": "xxx",
    "calls": [
        {
            "call_id": "ae5b182f-f37b-123e-dcb0-42010a34f811",
            "from": "xxx",
            "to": "xxx",
            "costs": [
                {
                    "direction": 1,
                    "currency": "EUR",
                    "price": 1.2948
                }
            ],
            "start_time": "1755153316",
            "end_time": "1755153319",
            "record": "https://xxx",
            "call_duration": 55,
            "fee_duration": 60,
            "bill_type": "6+6",
            "end_direction": 1,
            "end_reason": "Busy Here"
        }
    ]
}

calling涉及的响应码说明

code message 含义/解决办法
0 Success
-1 Failure 请联系技术人员排除问题
1000~100X Authentication failed 详情查看API鉴权部分
1100 Customer does not exist / Status is unavailable 账号状态异常，联系业务人员处理账号问题
1102 Insufficient balance 账号余额不足，请联系业务人员充值
9000 Request parameter error 参数缺失，请检查必须的参数
9001 System business error 系统业务错误，请联系技术人员排除问题
9002 Phone number error 非法号码，请检查号码正确性
9003 Customer APP does not exist / Status is unavailable 应用状态异常（不存在/禁用），联系业务人员处理云平台应用创建/禁用问题
10003 WhatsApp business phone is not bind app 该whatsapp号码未绑定应用，请联系业务人员处理应用和手机号绑定操作
10009 Calling line setting not exist calling线路配置出现异常
10010 Business phone no calling quotation 商户号未配置calling报价
10011 Get business phone sip password fail 获取商户号sip信息异常
10012 Calling setting fail {0} Calling配置出现异常
10013 Calling setting not exist Calling配置不存在
10014 Calling cdr not exist Calling cdr不存在
10015 {0} not in (0, 1) 参数不正确
10016 {0} has error 参数不合法

简介

短信

语音

云呼叫中心（NXLink）

云呼叫中心（AI自动外呼）

Flash Call

短链

邮件验证码

DID号码

通用

号码检测

WhatsApp

Viber

Zalo ZNS

Super Message API

隐私号(旧)

PNS

坐席（旧版）

AI Agent

Clone this wiki locally