Messaging

Verifications: send one-time codes on WhatsApp

Prove that a customer holds a phone number by sending a one-time code on WhatsApp from your own number, then checking the code they type.

Before Camille books a repair on her repair shop's website, the site needs to know that the number she typed is hers. It asks Heythere to start a verification: Heythere sends a six-digit code to Camille on WhatsApp, from the shop's own number, and the site checks the code she types. The shop needs no other provider for its codes.

startVerification takes the sending number, Camille's number, a purpose, and the language of the message. The purpose says why she receives a code: sign_in, sign_up, or action_confirmation, such as confirming a payment. checkVerificationCode then answers approved, incorrect with the attempts left, expired, or too_many_attempts.

What does Camille receive?

A WhatsApp message with her code and a button to copy it, sent through an authentication message template that Heythere creates on the shop's business account the first time it needs one. In Heythere, her conversation with the shop shows a verification_code message with its purpose and its delivery, never the code: Heythere keeps only a fingerprint of it. When Camille never wrote to the shop, she becomes a contact known by her phone number.

How long does a code work?

A code works for 10 minutes and takes 5 attempts. Starting a new verification of the same number and purpose replaces the pending one, so only the newer code works. Heythere refuses a code sent too soon after another, or too many codes to one number, one workspace, or one country, which keeps someone from flooding Camille with codes.

What does a code cost?

A delivered code counts in a billed conversation like any other message. A code WhatsApp never delivers is never billed.

Where to look when a code does not arrive?

getVerification shows how far WhatsApp carried the code, and why it failed when it did, such as a number that is not on WhatsApp. When WhatsApp refuses the code outright, startVerification answers with that reason at once.

In the API

Every operation is a REST endpoint and, unless marked REST only, an MCP tool of the same name. The OpenAPI document describes their parameters, payloads, and errors.

  • POST

    startVerification

    Send a one-time verification code on WhatsApp

    /api/organizations/{organizationId}/workspaces/{workspaceId}/verifications
  • POST

    checkVerificationCode

    Check a verification code

    /api/organizations/{organizationId}/workspaces/{workspaceId}/verifications/{verificationId}/check
  • GET

    getVerification

    Get a verification

    /api/organizations/{organizationId}/workspaces/{workspaceId}/verifications/{verificationId}