Skip to content

wa calling

Jump to bottom
GiuFLim edited this page Sep 18, 2025 · 32 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能力启用
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 Success outbound
inbound Object inbound

响应结果1

{
    "code": 0,
    "message": "Success",
    "data": {
        "sips": null,
        "status": 0,
        "business_phone": "85238533867",
        "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": "h3xOXEVB",
    "business_phone": "6287868572678",
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "85246771110",
    "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"
        }
    ]
}

简介

短信

语音

云呼叫中心（NXLink）

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

Flash Call

短链

邮件验证码

DID号码

通用

号码检测

WhatsApp

Viber

Zalo ZNS

Super Message API

隐私号(旧)

PNS

坐席（旧版）

AI Agent

Clone this wiki locally