VerifySpeed C#/.NET Client Library Documentation

The VerifySpeed .NET Client Library allows you to seamlessly integrate user verification features into your application. With support for multiple verification methods like Telegram, WhatsApp, and SMS, you can ensure a secure and reliable verification process for your users.

Setup

Step 1: Intall the Package

First, make sure you have installed the VerifySpeed package:

dotnet add package VerifySpeed.VSCSharp

Step 2: Service Registration

Next, add the VerifySpeed services to your application's dependency injection container in the Startup.cs or Program.cs file.

• .NET 5

  using VSCSharp;
  
  public class Startup
  {
      public void ConfigureServices(IServiceCollection services)
      {
          // Register VerifySpeed services with your server key
          services.AddVerifySpeed("YOUR_SERVER_KEY");
  
          // Add other services
      }
  
      public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
      {
      // Add your middlewares
      }
  }

• .NET 6+

  using VSCSharp;
  
  WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
  
  // Register VerifySpeed services with your server key.
  builder.Services.AddVerifySpeed("YOUR_SERVER_KEY");
  
  // Add other services
  
  WebApplication app = builder.Build();
  
  // Add your middlewares
  
  app.Run();

Usage

Below are examples of how to use the VerifySpeed client in your C# application.

note

Please read Verification Flow to undarstan the verification process.

1. Initializing the Client

Before creating a verification, you need to initialize the verification process to retrieve the available verification methods.

using System;
using System.Threading.Tasks;
using VSCSharp.Clients;
using VSCSharp.Exceptions;

public class VerifySpeedExample
{
    private readonly IVerifySpeedClient verifySpeedClient;

    public VerifySpeedExample(IVerifySpeedClient verifySpeedClient)
    {
        this.verifySpeedClient = verifySpeedClient;
    }

    public async Task InitializeVerificationAsync()
    {
        try
        {
            //TODO: Replace with the actual remote client IP address.
            string clientIp = "192.168.1.1";

            Initialization initialization = await verifySpeedClient.InitializeAsync(clientIp);
            
            Console.WriteLine("Available Verification Methods:");
            foreach (Method availableMethod in initialization.AvailableMethods)
            {
                Console.WriteLine($"- {availableMethod.DisplayName} ({availableMethod.MethodName})");
            }

            // in most cases, you may return the available methods to client.
        }
        catch (FailedInitializationException exeption)
        {
            Console.WriteLine($"Initialization failed: {exeption.Message}");
        }
    }
}

2. Creating a Verification

Once initialized, you can create a verification using the desired method (e.g., Telegram Message, WhatsApp Message).

note

NOTE: Please read Verification Flow and Verification Methods to undarstand the verification process.

using System;
using System.Threading.Tasks;
using VSCSharp.Clients;
using VSCSharp.Enums;
using VSCSharp.Exceptions;
using VSCSharp.Models.Commons;

public class VerificationCreationExample
{
    private readonly IVerifySpeedClient verifySpeedClient;

    public VerificationCreationExample(IVerifySpeedClient verifySpeedClient)
    {
        this.verifySpeedClient = verifySpeedClient;
    }

    public async Task CreateVerificationAsync()
    {
        try
        {
            //TODO: Replace with the actual remote client IP address.
            string clientIp = "192.168.1.1";

            CreatedVerification createdVerification = await verifySpeedClient.CreateVerificationAsync(
                methodType: MethodType.TelegramMessage,
                clientIPv4Address: clientIp,
                language: "en" // optional, but will be usefull if provided! (default is en for english)
            );

            Console.WriteLine($"Verification Method: {createdVerification.MethodName}");
            Console.WriteLine($"Verification Key: {createdVerification.VerificationKey}");
            Console.WriteLine($"Deep Link: {createdVerification.DeepLink}");

            // Use should return VerificationKey with DeepLink to the your mobile/web app
        }
        catch (FailedCreateVerificationException exeption)
        {
            Console.WriteLine($"Failed to create verification: {exeption.Message}");
        }
    }
}

Or use can input verification method name as string

CreatedVerification createdVerification = await verifySpeedClient.CreateVerificationAsync(
    methodName: "telegram-message",
    clientIPv4Address: clientIp,
    language: "ar"
);

3. Verifying a Token

After receiving a verification token from user, you can verify the token provided by the user and get verified phone number and other details.

using System;
using System.Threading.Tasks;
using VSCSharp.Clients;
using VSCSharp.Exceptions;

public class TokenVerificationExample
{
    private readonly IVerifySpeedClient verifySpeedClient;

    public TokenVerificationExample(IVerifySpeedClient verifySpeedClient)
    {
        verifySpeedClient = verifySpeedClient;
    }

    public async Task VerifyTokenAsync(string token)
    {
        try
        {
            VerificationResult result = await verifySpeedClient.VerifyTokenAsync(token);
            Console.WriteLine($"Verified Phone Number: {result.PhoneNumber}");
            Console.WriteLine($"Verification Method: {result.MethodName}");
            Console.WriteLine($"Date of Verification: {result.DateOfVerification}");
        }
        catch (FailedVerifyingTokenException exeption)
        {
            Console.WriteLine($"Token verification failed: {exeption.Message}");
        }
    }
}

Models

Initialization Response

• Initialization: Contains a list of available verification methods.

  public record Initialization
  {
      public List<Method> AvailableMethods { get; init; } = new();
  }
  
  public record Method
  {
      public string MethodName { get; init; } = null!;
      public string DisplayName { get; init; } = null!;
  }

Created Verification

• CreatedVerification: Provides details on the created verification, such as a key, its method name, and deep link (not null if method name is whatsapp-messege or telegram-message).

  public record CreatedVerification
  {
      public string MethodName { get; init; } = null!;
      public string VerificationKey { get; init; } = null!;
      public string? DeepLink { get; init; }
  }

Verification Result

• VerificationResult: Represents the outcome of verifying a user's token.

  public record VerificationResult
  {
      public string MethodName { get; init; } = null!;
      public DateTime DateOfVerification { get; init; }
      public string PhoneNumber { get; init; } = null!;
  }

Enums

• MethodType: Methods of verification. (Explanation)

public enum MethodType
{
    TelegramMessage,
    WhatsAppMessage,
    SmsOtp
}

Exceptions

Handle the following exceptions

• FailedInitializationException: Thrown when initialization fails.
• FailedCreateVerificationException: Thrown when verification creation fails.
• FailedVerifyingTokenException: Thrown when token verification fails.

API Example

Here is an use case example of this library for varifying users phone number.

using Microsoft.AspNetCore.Mvc;
using VSCSharp.Clients;
using VSCSharp.Models.Commons;
using VSCSharp.Enums;

[ApiController]
[Route("api/[controller]")]
public class VerificationController : ControllerBase
{
    private readonly IVerifySpeedClient verifySpeedClient;

    public VerificationController(IVerifySpeedClient verifySpeedClient)
    {
        verifySpeedClient = verifySpeedClient;
    }

    [HttpPost("initialize")]
    public async Task<IActionResult> PostVerificationInitialization()
    {
        try
        {
            var clientIp = HttpContext.Connection.RemoteIpAddress?.ToString();
            // NOTE: If your API is behind proxy or load balancer, get client's IP from 'X-Forwarded-For' header

            Initialization initialization = await verifySpeedClient.InitializeAsync(clientIp);

            return Ok(initialization);
        }
        catch (Exception exeption)
        {
            return BadRequest(exeption.Message);
        }
    }

    [HttpPost("create")]
    public async Task<IActionResult> PostVerificationCreation([FromBody] PostVerificationCreationRequest request)
    {
        try
        {
            var clientIp = HttpContext.Connection.RemoteIpAddress?.ToString();
            // NOTE: If your API is behind proxy or load balancer, get client's IP from 'X-Forwarded-For' header

            CreatedVerification verification = await verifySpeedClient.CreateVerificationAsync(
                request.MethodType,
                clientIp
            );

            return Ok(verification);
        }
        catch (Exception exeption)
        {
            return BadRequest(exeption.Message);
        }
    }

    [HttpGet("verify/{token}")]
    public async Task<IActionResult> GetTokenVerification(string token)
    {
        try
        {
            VerificationResult result = await verifySpeedClient.VerifyTokenAsync(token);
            // Now you can use verified phone number inside result object
            Console.WriteLine($"Verified Phone Number: {result.PhoneNumber}");

            return Ok(result);
        }
        catch (Exception exeption)
        {
            return BadRequest(exeption.Message);
        }
    }
}

public class PostVerificationCreationRequest
{
    [Required]
	public MethodType MethodType { get; set; }
}

License

This package is distributed under the MIT License.