Vonage Verify Python Library

Common errors

• NameError: name 'Vonage' is not defined

  cause Attempting to use `Vonage` class directly after only importing `vonage_verify`.
  fix You need to import `Vonage` from the main `vonage` package: `from vonage import Vonage, Auth`.

• vonage.errors.AuthenticationError: Could not authenticate with Vonage. Check your credentials.

  cause Incorrect `VONAGE_API_KEY` or `VONAGE_API_SECRET` environment variables, or hardcoded values are wrong/missing.
  fix Verify that your `VONAGE_API_KEY` and `VONAGE_API_SECRET` environment variables are correctly set and correspond to active credentials in your Vonage account dashboard. Ensure they are accessible by your Python script.

• vonage.errors.VerifyError: Your request is incomplete and missing the mandatory parameter $parameter

  cause A required parameter (e.g., 'brand', 'workflow', 'to' within a channel) was omitted or an invalid value was provided in the `VerifyRequest` constructor.
  fix Review the Vonage API documentation or the `vonage-verify` model definitions to ensure all mandatory parameters for your chosen verification workflow are provided and correctly formatted. For example, the `to` field for channels should be in E.164 format.

• vonage.errors.VerifyError: Concurrent verifications to the same number are not allowed

  cause An active verification request already exists for the target phone number.
  fix Wait for the ongoing verification to complete, fail, or expire before initiating a new one for the same number. Implement logic to check for existing verifications if this is a common scenario in your application.

• vonage.errors.VerifyError: The number you are trying to verify is blacklisted for verification. (Error Code 7)

  cause The phone number is blocked by the Vonage Anti-Fraud System or carrier-specific restrictions.
  fix This can indicate suspicious activity or network-level blocking. Review Vonage's documentation on the Verify Anti-Fraud System and consider checking if the number is on an unsupported network. If this persists for legitimate users, contact Vonage support.

Warnings

• breaking The legacy Number Verification API is deprecated and will sunset on September 30, 2025. Users should migrate to the unified Verify API with Silent Authentication for improved features and fallbacks.
  Fix: Migrate your integration to use the `vonage-verify` package with the `SilentAuthChannel` within a `workflow`. Refer to the Vonage Verify Migration Guide for detailed steps.
• breaking Changes to 10DLC brand verification processes, including the 'Authentication+' requirement for public profit brands, are being introduced (tentative date: October 17, 2024). This requires a 2FA email verification.
  Fix: If you are managing 10DLC brands, you may need to update your existing brands and provide a 'verification email' to re-verify the brand. This might involve triggering a `POST /brands/:brandId/revet` request via the Vonage APIs. Consult Vonage's 10DLC documentation for the latest requirements.
• gotcha The `vonage-verify` package is a component of the broader `vonage` Python SDK. It's recommended to install and use the main `vonage` package, and interact with verify functionality through the `vonage_client.verify` object. Directly instantiating classes from `vonage-verify` (e.g., `VerifyRequest`) is correct, but the client itself should come from `vonage`.
  Fix: Always install `pip install vonage` and instantiate your `vonage.Client` first. Then, import specific models like `VerifyRequest`, `SmsChannel`, etc., from `vonage_verify` as needed.

Install

• pip install vonage-verify Install vonage-verify
• pip install vonage Install main Vonage SDK (recommended)

Imports

• VerifyRequest

  from vonage_verify import VerifyRequest

• SmsChannel

  from vonage_verify import SmsChannel

• SilentAuthChannel

  from vonage_verify import SilentAuthChannel

• EmailChannel

  from vonage_verify import EmailChannel

• ChannelType

  from vonage_verify import ChannelType

• Vonage
  wrong:

  from vonage_verify import Vonage

  correct:

  from vonage import Vonage

  The Vonage client is part of the main `vonage` package, not `vonage-verify`.
• Auth
  wrong:

  from vonage_verify import Auth

  correct:

  from vonage import Auth

  The authentication object is part of the main `vonage` package.

Quickstart

This quickstart demonstrates how to initialize the Vonage client and send a verification request via SMS using `vonage-verify`. It uses environment variables for API credentials for security. The process involves creating a `VerifyRequest` with a specified `brand` and `workflow` (e.g., `SmsChannel`), and then calling `client.verify.start_verification`.

import os
from vonage import Vonage, Auth
from vonage_verify import VerifyRequest, SmsChannel

# Ensure VONAGE_API_KEY and VONAGE_API_SECRET are set as environment variables
client = Vonage(Auth(key=os.environ.get('VONAGE_API_KEY', ''), secret=os.environ.get('VONAGE_API_SECRET', '')))

# Define the recipient's phone number and brand name
recipient_number = os.environ.get('VONAGE_TEST_NUMBER', '1234567890') # Use E.164 format
brand_name = 'MyTestApp'

# Create an SMS channel for verification
sms_channel = SmsChannel(to=recipient_number)

# Construct the verification request with a workflow (SMS in this case)
params = {
    'brand': brand_name,
    'workflow': [sms_channel],
}
verify_request = VerifyRequest(**params)

try:
    # Start the verification process
    response = client.verify.start_verification(verify_request)
    print(f"Verification initiated. Request ID: {response['request_id']}")

    # In a real application, you would now prompt the user for the code
    # and then call client.verify.check_code(request_id=response['request_id'], code=user_entered_code)

    # Example of checking a code (assuming '1234' was sent and entered)
    # user_entered_code = '1234'
    # check_response = client.verify.check_code(request_id=response['request_id'], code=user_entered_code)
    # if check_response['status'] == '0':
    #     print('Verification successful!')
    # else:
    #     print(f"Verification failed: {check_response['error_text']}")

except Exception as e:
    print(f"An error occurred: {e}")