验证您的第一个客户
Bird Verify 确认某人拥有某个电子邮件地址或电话号码的控制权。您请求 Bird 发送一次性验证码。用户在您的应用中输入验证码，然后您向 Bird 查询是否匹配。Bird 生成并投递验证码，同时强制执行过期时间和尝试次数限制。您的应用永远不会接收或存储生成的验证码。
本快速入门验证您自己的电子邮件地址，无需任何设置。Bird 通过其共享的 Bird Verify 发送者发送邮件验证码，因此您不需要域名或余额。为 SMS 充值后，验证电话号码使用相同的两次调用。
1. 创建 API 密钥
在控制台中，前往 Developers > API keys 并创建一个密钥。密钥按区域划分，格式类似 bk_us1_... 或 bk_eu1_...；前缀中的区域告诉您应调用哪个 API 主机：https://us1.platform.bird.com 或 https://eu1.platform.bird.com。
完整密钥仅在创建时显示一次。将其复制到安全的地方，然后为发送示例导出：
代码示例
export BIRD_API_KEY="bk_us1_..."2. 发送验证码
为要确认的地址创建一次验证。唯一必填字段是 to。使用您自己的电子邮件地址，以便您能查收验证码。按照 SDK 快速入门安装适用于您所用语言的 Bird SDK。
在 SDK 选项卡中，运行代码前请替换示例 API 密钥和 user@example.com。CLI 使用您的登录凭据，cURL 选项卡使用 BIRD_API_KEY。
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });
const verification = await bird.verify.verifications.create({
to: { email: "user@example.com" },
});
console.log(verification.id, verification.status);from bird import APIError, Bird
with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
try:
verification = client.verify.verifications.create(
to={"email": "user@example.com"},
)
print(verification.id, verification.status)
except APIError as err:
print("could not start the verification:", err)package main
import (
"context"
"fmt"
"log"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
if err != nil {
log.Fatal(err)
}
verification, err := client.Verify.Verifications.Create(context.Background(), bird.VerifyVerificationsCreateParams{
To: bird.VerificationTo{Email: bird.Email("user@example.com")},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(verification.Id, *verification.Status)
}<?php
declare(strict_types=1);
require __DIR__ . '/../vendor/autoload.php';
use MessageBird\Bird;
use MessageBird\Wire\Model\VerificationCreateRequest;
use MessageBird\Wire\Model\VerificationTo;
$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');
$verification = $bird->verify->verifications->create(
(new VerificationCreateRequest())
->setTo((new VerificationTo())->setEmail('user@example.com')),
);
echo $verification->getId(), ' ', $verification->getStatus(), "\n";bird verify verifications create --email user@example.comcurl -X POST https://us1.platform.bird.com/v1/verify/verifications \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": { "email": "user@example.com" }
}'如果您的密钥以 bk_eu1_ 开头，请改为调用 https://eu1.platform.bird.com。
Bird 接受请求并开始发送验证码：
代码示例
{
"id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
"status": "pending",
"reason": null,
"to": { "email": "user@example.com" },
"channels": [{ "channel": "email" }],
"last_channel": "email",
"expires_at": "2026-07-23T14:55:58Z",
"verified_at": null,
"created_at": "2026-07-23T14:45:58Z",
"updated_at": "2026-07-23T14:45:58Z"
}无需存储验证 ID：第 3 步的校验以相同的收件人为键。邮件来自 Bird Verify <otp@verify.bird.com>，主题为 "Your verification code"，包含一个六位数验证码；邮件本身会说明过期时间。验证码长度、有效期、尝试次数上限和重新发送冷却时间均为工作区设置，验证设置列出了默认值和范围。
3. 校验验证码
从收件箱中取出验证码并提交，以相同的收件人为键：
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });
const result = await bird.verify.verifications.check({
to: { email: "user@example.com" },
code: "123456",
});
console.log(result.success);from bird import APIError, Bird
with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
try:
result = client.verify.verifications.check(
to={"email": "user@example.com"},
code="123456",
)
print(result.success)
except APIError as err:
print("could not check the passcode:", err)package main
import (
"context"
"fmt"
"log"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
if err != nil {
log.Fatal(err)
}
result, err := client.Verify.Verifications.Check(context.Background(), bird.VerifyVerificationsCheckParams{
To: bird.VerificationTo{Email: bird.Email("user@example.com")},
Code: "123456",
})
if err != nil {
log.Fatal(err)
}
fmt.Println(*result.Success)
}<?php
declare(strict_types=1);
require __DIR__ . '/../vendor/autoload.php';
use MessageBird\Bird;
use MessageBird\Wire\Model\VerificationCheckRequest;
use MessageBird\Wire\Model\VerificationTo;
$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');
$result = $bird->verify->verifications->check(
(new VerificationCheckRequest())
->setTo((new VerificationTo())->setEmail('user@example.com'))
->setCode('123456'),
);
echo $result->getSuccess() ? 'verified' : 'not verified', "\n";bird verify verifications check 123456 --email user@example.comcurl -X POST https://us1.platform.bird.com/v1/verify/verifications/check \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": { "email": "user@example.com" },
"code": "123456"
}'正确的验证码返回 success: true，嵌入的验证对象状态变为 verified：
代码示例
{
"success": true,
"reason": null,
"attempts_remaining": null,
"verification": {
"id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
"status": "verified",
"reason": null,
"to": { "email": "user@example.com" },
"channels": [{ "channel": "email" }],
"last_channel": "email",
"expires_at": "2026-07-23T14:55:58Z",
"verified_at": "2026-07-23T14:46:47Z",
"created_at": "2026-07-23T14:45:58Z",
"updated_at": "2026-07-23T14:46:47Z"
}
}在将此流程添加到注册环节之前，请处理以下结果：
- 校验失败返回 HTTP
200。 响应包含success: false、一个reason（incorrect_code、expired或attempts_exhausted），以及在还有剩余尝试次数时的attempts_remaining计数。在您的应用中根据此结果进行分支处理。验证在耗尽校验尝试次数后将永久失败。 - 验证仅解析一次。 达到
verified（或失败或过期）后，再次校验会返回404。将第一个确定性结果作为最终答案。如果用户需要新的验证码，请使用相同的收件人再次调用创建端点：进行中的验证会被复用，重新发送冷却时间过后将发出新的验证码。
您创建的每次验证都会显示在 Verifications 页面上，包含状态、收件人、渠道和时间信息。生成的验证码不会显示。
改为验证电话号码
要通过 SMS 进行验证，请在 to 中填入 E.164 格式的电话号码，而非电子邮件地址：
const verification = await bird.verify.verifications.create({
to: { phone_number: "+15551234567" },
});
console.log(verification.id, verification.status);verification = client.verify.verifications.create(to={"phone_number": "+15551234567"})
print(verification.id, verification.status)verification, err := client.Verify.Verifications.Create(context.Background(), bird.VerifyVerificationsCreateParams{
To: bird.VerificationTo{PhoneNumber: bird.String("+15551234567")},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(verification.Id, *verification.Status)$verification = $bird->verify->verifications->create(
(new VerificationCreateRequest())->setTo((new VerificationTo())->setPhoneNumber('+15551234567')),
);
echo $verification->getId(), ' ', $verification->getStatus();bird verify verifications create --body-file - <<'JSON'
{
"to": {
"phone_number": "+15551234567"
},
"metadata": {
"correlation_id": "signup-7f3a"
}
}
JSONcurl -X POST "https://{region}.platform.bird.com/v1/verify/verifications" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": {
"phone_number": "+15551234567"
},
"metadata": {
"correlation_id": "signup-7f3a"
}
}'校验步骤完全相同：将 email 替换为相同的 phone_number。电话投递从您工作区的 SMS 余额中扣费，目的地国家决定路由。Bird 在大多数国家优先使用 WhatsApp，在部分国家优先使用 SMS。国家配置显示并配置每个目的地的可用渠道及其顺序。发送者与品牌展示每个渠道上用户收到的内容。
通过两个渠道触达用户
您不必只选择一个渠道。在 to 中同时包含 email 和 phone_number，Bird 会根据您的国家配置生成投递计划，该配置显示每个目的地的可用渠道及其顺序。Bird 按计划依次尝试，直到发送被接受。如果投递随后彻底失败，Bird 会通过下一个渠道发送新的验证码。使用创建验证时相同的 to 对象来校验验证码。用户输入收到的任一验证码即可。
后续步骤
- 发送验证：深入了解选项、状态、重新发送、设置和限制。
- 国家配置：启用国家并设置每个国家的渠道顺序。
- 发送者与品牌：验证码消息的外观，以及如何从您自己的域名发送邮件。
- Verify API 参考：完整的请求和响应结构。
- 在注册时验证手机号码：一段将相同流程集成到网上商店的视频。