> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wtocrm.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 面向中国外贸出口团队与软件开发者，介绍 WTOCRM WhatsApp 协议 API：通过扫码或配对码关联账号，确认连接后发送消息，并用 Webhook 将海外客户回复接入自己的 CRM、ERP 或 SaaS。

海外买家在 WhatsApp 上问报价，业务员在手机里回复，客户资料却留在另一套系统里。等到你要确认样品、补充规格或安排下一次跟进，就得重新寻找聊天记录。

**WTOCRM WhatsApp API（WTO WA API）让你通过扫码或配对码关联 WhatsApp 账号，连接成功后通过接口收发消息。** 你可以把它接入自己的外贸 CRM、ERP 或跨境 SaaS，让客户沟通围绕业务流程展开。

对于外贸团队，它提供了把聊天接入工作系统的通道；对于开发者，你可以沿用现有后端，通过 REST API 发起操作，用 Webhook 接收事件。从[连接第一个 WhatsApp 实例](https://docs.wtocrm.com/zh-Hans/waapi/connect-instance.md)开始，就能逐步验证整个消息流程。

> **接入要点**
>
> * WTO WA API 提供 WhatsApp 协议接入，支持二维码和手机号码配对码两种登录方式。
> * 配对码需要在手机 WhatsApp 中输入；二维码需要在关联设备流程中扫描。
> * 登录码不代表登录成功。发送前先确认 `instance.state` 为 `open`。
> * REST API 负责发起消息操作，Webhook 将客户回复和连接事件交给你的应用。

![手机通过连接光带关联外贸消息窗口，背景为港口与集装箱轮廓的概念插画](https://assets.wtocrm.com/blog/2026/whatsapp-api-for-export-business/cover-fc11b84da5.webp)

外贸消息集成概念插画，不是真实产品截图。

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

当一段聊天需要触发后续工作，你就需要在消息与业务数据之间建立联系。比如买家确认了型号，业务员需要更新报价；客户回复了收货地址，跟单人员需要核对样品寄送信息。

如果你正在开发外贸软件，可以先选择一个具体任务：**在客户详情页发送报价沟通，并把客户回复关联回对应联系人。** 这个任务既能验证消息通道，也能验证你的系统是否正确识别了客户。

WTO WA API 提供消息操作接口；联系人匹配、报价审批、订单查询和任务分配由你的应用实现。如果你还在评估整体接入方式，可以结合[开发者 API 概览](https://docs.wtocrm.com/zh-Hans/blog/whatsapp-api-for-developers.md)了解连接状态与事件处理。

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

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

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

本文介绍 WTOCRM 提供的关联设备协议接入，不属于 Meta 官方 WhatsApp Business Platform／Cloud API 接入。关联设备登录需要账号持有人操作；连接和使用仍受网络、账号状态及平台规则影响。

本指南由 [WTOCRM](https://wtocrm.com) 发布，说明其 WhatsApp API 的使用方式。连接、消息与 Webhook 的参数以本文链接的产品接口文档为准。

从[WTO WA API 接口目录](https://docs.wtocrm.com/zh-Hans/waapi/index.md)查看支持的操作。先跑通文本收发，再按实际需要扩展媒体与其他能力。

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

先按[创建实例文档](https://docs.wtocrm.com/zh-Hans/waapi/create-instance.md)准备关联设备实例，再打开[连接实例指南](https://docs.wtocrm.com/zh-Hans/waapi/connect-instance.md)。准备实例名称、具备访问权限的 API 凭证，以及装有 WhatsApp 的账号手机。凭证保留在后端，替换下面的示例占位值后再测试。

两种方式调用同一个连接接口：不传 `number` 获取二维码；传入 `number` 请求手机号码配对码。

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

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

```bash theme={null}
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 手机号码：

```bash theme={null}
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` 是二维码内容。** 不要把两个字段混用，也不要频繁重复请求配对码，以免生成新码后仍输入旧码。字段暂未返回时，按连接指南等待后重试。

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

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

### 确认连接状态

调用[连接状态查询接口](https://docs.wtocrm.com/zh-Hans/waapi/get-connection-state.md)：

```bash theme={null}
curl --request GET \
  --url 'https://waapi.wtocrm.com/instance/connectionState/export-demo' \
  --header 'apikey: YOUR_API_KEY'
```

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

### 发送第一条测试消息

向你自己的测试收件号码发送一条明确的测试消息。以下请求结构依据[发送文本消息文档](https://docs.wtocrm.com/zh-Hans/waapi/send-text-message.md)，将号码替换为你的测试号码：

```bash theme={null}
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://docs.wtocrm.com/zh-Hans/waapi/set-webhook.md)配置你的 HTTPS 回调地址及所需事件。按实例实际支持的事件配置消息回调；连接指南还列出了 `CONNECTION_UPDATE`，可用于更新连接状态。

让测试收件人回复一条消息，检查后端是否收到事件，再验证消息是否进入正确的联系人和实例。Webhook 接收服务应按消息标识去重，并区分入站消息与自己发出的消息，避免重复跟进或自动回复循环。

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

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

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

这些是你可以构建的集成方式。报价、订单和任务不会仅因账号登录就自动同步，需要由你的应用连接对应业务数据。需要发送图片或资料时，继续查看[媒体消息接口](https://docs.wtocrm.com/zh-Hans/waapi/send-media-message.md)。

将消息用于客户已同意的业务沟通。先验证一个测试实例的完整收发，再扩展号码、团队和自动化规则。

## 开发者常见问题

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

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

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

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

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

二维码只是登录凭据。账号持有人还需要扫码完成关联；字段生成中、手机未确认或连接未完成时，都应先检查状态，等待 `open` 后继续。具体排查步骤见[连接实例指南](https://docs.wtocrm.com/zh-Hans/waapi/connect-instance.md)。

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

你可以使用这些语言的 HTTP 客户端调用 REST 接口，并用自己的后端接收 Webhook。本文不依赖特定 SDK；按照接口文档处理认证、请求结构和返回结果即可。

**从连接你的第一个 WhatsApp 实例开始。** 选择扫码或配对码登录，验证 `open` 状态，发送一条测试消息，再接住回复。打开 [WTOCRM WhatsApp API 连接指南](https://docs.wtocrm.com/zh-Hans/waapi/connect-instance.md)，把消息收发接入你的外贸软件。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.