2.2.2.3 PHP

VerifySpeed PHP Client Library Documentation

The VerifySpeed PHP client library lets you create verifications from your backend. It supports message-based methods (WhatsApp Message, Telegram Message) and OTP methods (WhatsApp OTP, Telegram OTP, SMS OTP).

note

Please read Verification Flow and Verification Methods to understand the verification process.

Setup

Step 1: Install the Package

composer require verifyspeed/vs-php

The package depends on Guzzle for HTTP requests and libphonenumber-for-php to validate and normalize phone numbers for OTP methods.

Step 2: Configure the Server Key

Set your server key once before calling any API methods. You can obtain the key from the dashboard.

<?php

use VerifySpeed\VerifySpeed;

VerifySpeed::setServerKey('YOUR_SERVER_KEY');

Usage

Creating a Verification

Call VerifySpeed::createVerification() with the method name and the client's IPv4 address. For OTP methods, you must also pass a phone number; VerifySpeed sends a one-time password to that number.

createVerification parameters

Parameter	Required	Description
$methodName	Yes	Verification method identifier (e.g., telegram-message, whatsapp-otp).
$clientIpv4Address	Yes	The client's IPv4 address, sent as the client-ipv4-address request header.
$language	No	Language for the verification flow (e.g., en, ar, ckb).
$phoneNumber	For OTP methods	User's phone number. Required when $methodName is whatsapp-otp, telegram-otp, or sms-otp. The library validates and normalizes the number to E.164 format before sending the request. Omit for message-based methods.

If $methodName is an OTP type and $phoneNumber is omitted or empty, the client throws InvalidArgumentException with the message Phone number is required for OTP verification methods (whatsapp-otp, telegram-otp, sms-otp).

/**
 * Creates a verification.
 *
 * @param string      $methodName         Verification method identifier (e.g., "whatsapp-message", "whatsapp-otp").
 * @param string      $clientIpv4Address  Client IPv4 address for the request header.
 * @param string|null $language           Optional language (e.g., "en", "ar", "ckb").
 * @param string|null $phoneNumber        User phone number. Required for OTP methods; normalized to E.164.
 *                                         VerifySpeed sends a one-time password to this number. Omit for message-based methods.
 * @return VerificationResult
 *
 * @throws \InvalidArgumentException When required arguments are missing or invalid.
 * @throws \RuntimeException         When the server key is not set or the API request fails.
 */
VerifySpeed::createVerification(
    string $methodName,
    string $clientIpv4Address,
    ?string $language = null,
    ?string $phoneNumber = null
): VerificationResult;

Message-based method

For message-based methods (whatsapp-message, telegram-message), omit $phoneNumber. The response includes a deep link for the client app.

<?php

use VerifySpeed\VerifySpeed;
use VerifySpeed\VerificationResult;

VerifySpeed::setServerKey('YOUR_SERVER_KEY');

try {
    // Replace with the actual remote client IP address.
    $clientIp = '192.168.1.1';

    $result = VerifySpeed::createVerification(
        methodName: 'telegram-message',
        clientIpv4Address: $clientIp,
        language: 'ar'
    );

    echo "Method: {$result->getMethodName()}\n";
    echo "Verification Key: {$result->getVerificationKey()}\n";
    echo "Deep Link: {$result->getDeepLink()}\n";

    // Return verificationKey and deepLink to your mobile/web app.
} catch (\InvalidArgumentException $e) {
    echo "Invalid input: {$e->getMessage()}\n";
} catch (\RuntimeException $e) {
    echo "Request failed: {$e->getMessage()}\n";
}

OTP-based method

For OTP methods (whatsapp-otp, telegram-otp, sms-otp), pass $phoneNumber. VerifySpeed sends the OTP to that number; your client app collects the code from the user and completes verification through the SDK.

<?php

use VerifySpeed\VerifySpeed;

VerifySpeed::setServerKey('YOUR_SERVER_KEY');

try {
    $clientIp = '192.168.1.1';

    $result = VerifySpeed::createVerification(
        methodName: 'whatsapp-otp',
        clientIpv4Address: $clientIp,
        language: 'en',
        phoneNumber: '+14255552673'
    );

    echo "Verification Key: {$result->getVerificationKey()}\n";
    // getDeepLink() is null for OTP methods — return verificationKey to your client app.
} catch (\InvalidArgumentException $e) {
    echo "Invalid input: {$e->getMessage()}\n";
} catch (\RuntimeException $e) {
    echo "Request failed: {$e->getMessage()}\n";
}

Models

VerificationResult

Returned by createVerification(). Contains the verification key and, for message-based methods, a deep link.

Method	Description
getMethodName()	The verification method used (e.g., whatsapp-otp).
getVerificationKey()	Key that identifies this verification; pass to your client SDK.
getDeepLink()	URL for deep-link verification. null for OTP methods.
toArray()	Associative array with methodName, verificationKey, and deepLink.

public function __construct(
    private readonly string $methodName,
    private readonly string $verificationKey,
    private readonly ?string $deepLink
) {}

• deepLink is set for message-based methods (whatsapp-message, telegram-message).
• deepLink is null for OTP methods (whatsapp-otp, telegram-otp, sms-otp).

Exceptions

Exception	When thrown
\InvalidArgumentException	Empty server key, method name, or client IP; missing phone number for OTP methods; invalid phone number format.
\RuntimeException	Server key not set (setServerKey not called); non-success HTTP response; network or deserialization errors.

Phone number validation

For OTP methods, the library uses libphonenumber to parse and validate $phoneNumber and formats it as E.164 before calling the API. Invalid numbers throw InvalidArgumentException with a message such as Invalid phone number format. Please use E.164 format (e.g., +1234567890).

API Example (Laravel)

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Routing\Controller;
use VerifySpeed\VerifySpeed;
use VerifySpeed\VerificationResult;

class VerificationController extends Controller
{
    public function __construct()
    {
        VerifySpeed::setServerKey(config('services.verifyspeed.server_key'));
    }

    public function create(Request $request)
    {
        $request->validate([
            'methodName' => 'required|string',
            'phoneNumber' => 'nullable|string',
            'language' => 'nullable|string',
        ]);

        try {
            $clientIp = $request->ip();
            // If your API is behind a proxy or load balancer, use X-Forwarded-For instead.

            $verification = VerifySpeed::createVerification(
                methodName: $request->input('methodName'),
                clientIpv4Address: $clientIp,
                language: $request->input('language'),
                phoneNumber: $request->input('phoneNumber')
            );

            return response()->json($verification->toArray());
        } catch (\InvalidArgumentException $e) {
            return response()->json(['error' => $e->getMessage()], 400);
        } catch (\RuntimeException $e) {
            return response()->json(['error' => $e->getMessage()], 502);
        }
    }
}

Verifying Tokens

To decrypt and validate verification tokens returned by the client SDK, use the EncryptionTool class from the same package. See Verification Result Documentation.

License

This package is distributed under the MIT License.