An in-house API gateway for WhatsApp messaging

Integration Guide

Getting an application to talk to WApi end to end takes three steps: get an API key, open a session, send a message. The examples below show each step of a typical integration using the placeholder YOUR_API_KEY variable.

1. 1 · Create an API key

   On first setup, the Security:MasterKey value in appsettings.json is your first Admin key; you create subsequent keys with it. For day-to-day operations, it is recommended to use work keys with the appropriate role (Operator/Viewer) instead of the Master key.

   curl -X POST https://wapi.erp.tr/api/auth/api-keys \
        -H "X-API-Key: $MASTER_KEY" \
        -H "Content-Type: application/json" \
        -d '{ "name": "billing-app-prod", "role": 1, "allowedIps": "203.0.113.0/24" }'
   
   # Response: the created apiKey is returned raw **only once**. Store it.
   # { "dto": { ... }, "apiKey": "wapi_..." }

   Roles: 0 = Viewer, 1 = Operator, 2 = Admin.

2. 2 · Open a session and link the phone

   Each WhatsApp number is kept as a separate session. With the node-bridge engine, a QR code is generated when the session starts; the phone pairs by scanning this QR from the WhatsApp app via Settings → Linked Devices → Link a Device. After pairing, the auth state is stored on disk; no rescan is needed even if the service restarts.

   # Create session
   curl -X POST https://wapi.erp.tr/api/sessions \
        -H "X-API-Key: $YOUR_API_KEY" -H "Content-Type: application/json" \
        -d '{ "name": "sales-department", "proxyUrl": null, "proxyType": null }'
   
   # Store the id from the response; every endpoint from here on takes that id.
   SESSION_ID=...
   
   # Start the session (brings up the engine; generates the QR)
   curl -X POST https://wapi.erp.tr/api/sessions/$SESSION_ID/start \
        -H "X-API-Key: $YOUR_API_KEY"
   
   # Fetch the QR — returned as a base64 PNG (can be used directly as an img src)
   curl https://wapi.erp.tr/api/sessions/$SESSION_ID/qr \
        -H "X-API-Key: $YOUR_API_KEY"
   # { "sessionId": "...", "qrCode": "data:image/png;base64,iVBORw...", "status": 0 }

3. 3 · Send a message

   Once the session moves to the connected state, any message endpoint can be called. Below is a minimal integration close to real production code in each language.

   C# VB.NET Java curl HTTP / Swagger

   // .NET 8+ — minimal client with HttpClient
   using System.Net.Http.Headers;
   using System.Net.Http.Json;
   
   var http = new HttpClient { BaseAddress = new Uri("https://wapi.erp.tr") };
   http.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
   
   // Send message
   var payload = new { chatId = "905321234567@s.whatsapp.net", text = "Hello!" };
   var res = await http.PostAsJsonAsync($"/api/sessions/{sessionId}/messages/send-text", payload);
   res.EnsureSuccessStatusCode();
   var msg = await res.Content.ReadFromJsonAsync<MessageDto>();
   Console.WriteLine($"WApi message id: {msg!.Id}  WhatsApp id: {msg.WaMessageId}");
   
   // Error check
   if (msg.Status == MessageStatus.Failed)
       throw new Exception("The message was not accepted by the engine.");
   
   public record MessageDto(Guid Id, Guid SessionId, string? WaMessageId,
       string ChatId, string? Body, int Type, int Direction, int Status,
       long Timestamp, DateTime CreatedAt);
   
   public enum MessageStatus { Pending = 0, Sent = 1, Delivered = 2, Read = 3, Failed = 4 }