外贸软件如何接入 WhatsApp？WTOCRM API 扫码与配对码登录指南

海外买家在 WhatsApp 上问报价，业务员在手机里回复，客户资料却留在另一套系统里。等到你要确认样品、补充规格或安排下一次跟进，就得重新寻找聊天记录。 WTOCRM WhatsApp API（WTO WA API）让你通过扫码或配对码关联 WhatsApp 账号，连接成功后通过接口收发消息。 你可以把它接入自己的外贸 CRM、ERP 或跨境 SaaS，让客户沟通围绕业务流程展开。对于外贸团队，它提供了把聊天接入工作系统的通道；对于开发者，你可以沿用现有后端，通过 REST API 发起操作，用 Webhook 接收事件。从连接第一个 WhatsApp 实例开始，就能逐步验证整个消息流程。

接入要点

WTO WA API 提供 WhatsApp 协议接入，支持二维码和手机号码配对码两种登录方式。

配对码需要在手机 WhatsApp 中输入；二维码需要在关联设备流程中扫描。

登录码不代表登录成功。发送前先确认 instance.state 为 open。

REST API 负责发起消息操作，Webhook 将客户回复和连接事件交给你的应用。

手机通过连接光带关联外贸消息窗口，背景为港口与集装箱轮廓的概念插画 — 外贸消息集成概念插画，不是真实产品截图。

外贸团队为什么需要把 WhatsApp 接入业务系统？

当一段聊天需要触发后续工作，你就需要在消息与业务数据之间建立联系。比如买家确认了型号，业务员需要更新报价；客户回复了收货地址，跟单人员需要核对样品寄送信息。如果你正在开发外贸软件，可以先选择一个具体任务：在客户详情页发送报价沟通，并把客户回复关联回对应联系人。 这个任务既能验证消息通道，也能验证你的系统是否正确识别了客户。 WTO WA API 提供消息操作接口；联系人匹配、报价审批、订单查询和任务分配由你的应用实现。如果你还在评估整体接入方式，可以结合开发者 API 概览了解连接状态与事件处理。

WTOCRM WhatsApp 协议 API 提供哪些接入能力？

WTO WA API 使用关联设备会话连接 WhatsApp，把连接和消息操作开放为 HTTP 接口。你可以使用支持 HTTP 请求的现有技术栈，开发自己的用户界面与业务规则。

接入能力	你可以如何使用
扫码登录	在你的连接页面展示二维码，由账号持有人在手机上扫描关联
配对码登录	提交 WhatsApp 手机号码，获取配对码，由账号持有人在手机上输入
文本与媒体消息接口	在业务页面发起沟通，按接口能力扩展产品图片或资料发送
连接状态查询	在发送前确认账号连接，并在页面展示当前状态
Webhook	将消息及连接事件接入后端，触发你定义的跟进流程

本文介绍 WTOCRM 提供的关联设备协议接入，不属于 Meta 官方 WhatsApp Business Platform／Cloud API 接入。关联设备登录需要账号持有人操作；连接和使用仍受网络、账号状态及平台规则影响。本指南由 WTOCRM 发布，说明其 WhatsApp API 的使用方式。连接、消息与 Webhook 的参数以本文链接的产品接口文档为准。从WTO WA API 接口目录查看支持的操作。先跑通文本收发，再按实际需要扩展媒体与其他能力。

扫码或配对码：选择一种方式连接账号

先按创建实例文档准备关联设备实例，再打开连接实例指南。准备实例名称、具备访问权限的 API 凭证，以及装有 WhatsApp 的账号手机。凭证保留在后端，替换下面的示例占位值后再测试。两种方式调用同一个连接接口：不传 number 获取二维码；传入 number 请求手机号码配对码。

扫码登录：展示二维码，在手机上确认关联

从后端发起以下请求，将 export-demo 替换为你的实例名称：

curl --request GET \
  --url 'https://waapi.wtocrm.com/instance/connect/export-demo' \
  --header 'apikey: YOUR_API_KEY'

读取返回的 base64 并显示为二维码图片，或将 code 编码为二维码。base64 已包含 PNG 数据 URL 前缀；code 是二维码原始内容。账号持有人在手机 WhatsApp 中打开 关联设备，选择 关联设备 并扫描二维码。你的应用只向获授权的账号持有人展示登录二维码。

配对码登录：输入手机号，再到手机上输入配对码

需要用配对码关联时，在连接请求中传入 WhatsApp 手机号码：

curl --request GET \
  --url 'https://waapi.wtocrm.com/instance/connect/export-demo?number=5511999999999' \
  --header 'apikey: YOUR_API_KEY'

示例号码仅用于展示格式。替换为你自己的 WhatsApp 号码，包含国家码，总计 8–15 位数字，不带 +、空格、标点或前导零。读取响应中的 pairingCode。账号持有人在该号码的手机 WhatsApp 中进入 关联设备，选择关联设备流程中的 改用手机号码关联，输入配对码完成确认。菜单名称可能随应用版本变化。 pairingCode 才是需要输入的配对码，code 是二维码内容。 不要把两个字段混用，也不要频繁重复请求配对码，以免生成新码后仍输入旧码。字段暂未返回时，按连接指南等待后重试。

从连接成功到开始聊天：发送消息并接收回复

完成手机操作后，先验证连接，再发送测试消息。一个完整的接入结果应当是：你的应用能发出消息、测试收件人能收到、回复事件能进入你的后端。

确认连接状态

调用连接状态查询接口：

curl --request GET \
  --url 'https://waapi.wtocrm.com/instance/connectionState/export-demo' \
  --header 'apikey: YOUR_API_KEY'

等待 instance.state 为 open 再发送。connecting 表示仍在连接，close 表示已断开。拿到二维码、配对码或 HTTP 成功响应，都不能替代这一步。

发送第一条测试消息

向你自己的测试收件号码发送一条明确的测试消息。以下请求结构依据发送文本消息文档，将号码替换为你的测试号码：

curl --request POST \
  --url 'https://waapi.wtocrm.com/message/sendText/export-demo' \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"number":"5511999999999","textMessage":{"text":"WTOCRM integration test: please reply to confirm receipt."}}'

检查接口结果，同时在收件手机确认实际接收。接口返回结果与最终送达是不同环节；请求超时时，先核对处理结果再决定是否重试，避免重复发送。

用 Webhook 接收客户回复

按设置 Webhook 文档配置你的 HTTPS 回调地址及所需事件。按实例实际支持的事件配置消息回调；连接指南还列出了 CONNECTION_UPDATE，可用于更新连接状态。让测试收件人回复一条消息，检查后端是否收到事件，再验证消息是否进入正确的联系人和实例。Webhook 接收服务应按消息标识去重，并区分入站消息与自己发出的消息，避免重复跟进或自动回复循环。

用一个外贸场景，把消息能力接进现有软件

先从“询盘到报价沟通”开始：业务员在客户页面发出沟通消息，客户回复进入 Webhook，你的应用把回复关联到该客户，再由业务员确认下一步。

外贸任务	API 提供的通道	你需要在业务系统实现的逻辑
询盘回复	发送文本、接收消息事件	匹配联系人，记录询盘来源与负责人
报价沟通	发送文本或按媒体接口发送资料	选择正确版本，审批报价与交期
样品跟进	发送进度信息、接收确认	关联样品单，核对寄送信息
发货与售后	发送通知、接收回复	查询订单状态，创建处理任务

这些是你可以构建的集成方式。报价、订单和任务不会仅因账号登录就自动同步，需要由你的应用连接对应业务数据。需要发送图片或资料时，继续查看媒体消息接口。将消息用于客户已同意的业务沟通。先验证一个测试实例的完整收发，再扩展号码、团队和自动化规则。

开发者常见问题

扫码登录后，业务员可以直接在自己的软件里聊天吗？

连接成功后，你的软件可以通过发送接口与 Webhook 构建聊天功能。消息列表、联系人关联、访问权限和聊天界面需要由你的应用实现；如果你需要现成的工作台，可以另行了解 WTOCRM 的会话功能。

配对码需要输入到哪里？

输入到该账号的手机 WhatsApp 关联设备流程中。API 返回 pairingCode，你的应用负责向账号持有人展示。手机确认后，再查询连接状态。

已经拿到二维码，为什么还不能发消息？

二维码只是登录凭据。账号持有人还需要扫码完成关联；字段生成中、手机未确认或连接未完成时，都应先检查状态，等待 open 后继续。具体排查步骤见连接实例指南。

可以用 Python、Java、PHP 或 Node.js 接入吗？

你可以使用这些语言的 HTTP 客户端调用 REST 接口，并用自己的后端接收 Webhook。本文不依赖特定 SDK；按照接口文档处理认证、请求结构和返回结果即可。 从连接你的第一个 WhatsApp 实例开始。 选择扫码或配对码登录，验证 open 状态，发送一条测试消息，再接住回复。打开 WTOCRM WhatsApp API 连接指南，把消息收发接入你的外贸软件。

​外贸团队为什么需要把 WhatsApp 接入业务系统？

​WTOCRM WhatsApp 协议 API 提供哪些接入能力？

​扫码或配对码：选择一种方式连接账号

​扫码登录：展示二维码，在手机上确认关联

​配对码登录：输入手机号，再到手机上输入配对码

​从连接成功到开始聊天：发送消息并接收回复

​确认连接状态

​发送第一条测试消息

​用 Webhook 接收客户回复

​用一个外贸场景，把消息能力接进现有软件

​开发者常见问题

​扫码登录后，业务员可以直接在自己的软件里聊天吗？

​配对码需要输入到哪里？

​已经拿到二维码，为什么还不能发消息？

​可以用 Python、Java、PHP 或 Node.js 接入吗？