Developer Reference • Version 1.0

Client Integration Guide

Messaging & Contacts REST API — Implementation reference for contacts, groups, automated replies, and outbound WhatsApp messaging.

Base URL
https://app.waserve.com
Authentication
Bearer Token
Content-Type
application/json
API Resources
15 Endpoints
Documentation Menu
Generate API Key

1. API at a Glance

Use this quick overview to understand the API architecture before starting integration. Replace {{base_url}} with your API host, add your Bearer Token, and send JSON for all requests.

Endpoint Map

Resource Method Route Purpose
Contacts GET /api/contacts List contacts collection
Contacts POST /api/contacts Create a new contact
Contacts PUT /api/contacts/{uuid} Update contact by UUID
Contacts DELETE /api/contacts/{uuid} Delete contact by UUID
Contact Groups GET /api/contact-groups List all contact groups
Contact Groups POST /api/contact-groups Create a new contact group
Contact Groups PUT /api/contact-groups/{uuid} Rename / update group
Contact Groups DELETE /api/contact-groups/{uuid} Delete contact group
Automated Replies GET /api/canned-replies List automated reply rules
Automated Replies POST /api/canned-replies Create automated reply rule
Automated Replies PUT /api/canned-replies/{uuid} Update automated reply rule
Automated Replies DELETE /api/canned-replies/{uuid} Delete automated reply rule
Messages POST /api/send Send text / interactive message
Messages POST /api/send/media Send image, audio, video, document
Messages POST /api/send/template Send approved WhatsApp template
Request conventions: All example URLs are relative to {{base_url}}. Protected requests require Authorization: Bearer YOUR_AUTHORIZATION_TOKEN. Routes containing {uuid} require the record's UUID string.

2. Authentication & Request Format

WAServe uses Bearer Token authentication. Send your secret access token in the Authorization header on every request.

HTTP Headers 
Authorization: Bearer YOUR_AUTHORIZATION_TOKEN
Content-Type: application/json

Base Request Pattern

cURL Pattern 
curl -X METHOD '{{base_url}}/api/...' \
  -H 'Authorization: Bearer YOUR_AUTHORIZATION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
Security Requirement: Store your API token on your backend server or secret manager. Never expose Bearer tokens in frontend JavaScript, public GitHub repos, or browser network logs.

3. Contacts

Create, retrieve, update, and delete individual contact records programmatically.

GET /api/contacts
3.1 Get Contact List

Returns the paginated contact collection.

cURL 
curl -X GET '{{base_url}}/api/contacts' \
  -H 'Authorization: Bearer YOUR_AUTHORIZATION_TOKEN' \
  -H 'Content-Type: application/json'
POST /api/contacts
3.2 Add Contact

Creates a new contact record.

Request Fields
Field Type Example Description
first_name string John Contact first name
last_name string Doe Contact last name
email string johndoe@gmail.com Contact email address
phone string +19680825846 Contact phone number with country code
cURL Request 
curl -X POST '{{base_url}}/api/contacts' \
  -H 'Authorization: Bearer YOUR_AUTHORIZATION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@gmail.com",
    "phone": "+19680825846"
  }'
PUT /api/contacts/{uuid}
3.3 Edit Contact

Updates an existing contact identified by UUID.

cURL Request 
curl -X PUT '{{base_url}}/api/contacts/{uuid}' \
  -H 'Authorization: Bearer YOUR_AUTHORIZATION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@gmail.com",
    "phone": "+19680825846"
  }'
DELETE /api/contacts/{uuid}
3.4 Delete Contact

Deletes the selected contact permanently.

cURL Request 
curl -X DELETE '{{base_url}}/api/contacts/{uuid}' \
  -H 'Authorization: Bearer YOUR_AUTHORIZATION_TOKEN' \
  -H 'Content-Type: application/json'

4. Contact Groups

Organize contacts into named groups for targeted WhatsApp campaign broadcasts and segmentation.

GET /api/contact-groups
4.1 Get Contact Groups List
cURL 
curl -X GET '{{base_url}}/api/contact-groups' \
  -H 'Authorization: Bearer YOUR_AUTHORIZATION_TOKEN' \
  -H 'Content-Type: application/json'
POST /api/contact-groups
4.2 Create Contact Group
cURL Request 
curl -X POST '{{base_url}}/api/contact-groups' \
  -H 'Authorization: Bearer YOUR_AUTHORIZATION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name": "VIP Customers"}'
PUT /api/contact-groups/{uuid}
4.3 Update Contact Group
cURL Request 
curl -X PUT '{{base_url}}/api/contact-groups/{uuid}' \
  -H 'Authorization: Bearer YOUR_AUTHORIZATION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Lead Segment Q3"}'
DELETE /api/contact-groups/{uuid}
4.4 Delete Contact Group
cURL Request 
curl -X DELETE '{{base_url}}/api/contact-groups/{uuid}' \
  -H 'Authorization: Bearer YOUR_AUTHORIZATION_TOKEN' \
  -H 'Content-Type: application/json'

5. Automated Replies (Canned Responses)

Manage instant automated response rules triggered by incoming message keywords and patterns.

GET /api/canned-replies
5.1 List Automated Replies
cURL 
curl -X GET '{{base_url}}/api/canned-replies' \
  -H 'Authorization: Bearer YOUR_AUTHORIZATION_TOKEN' \
  -H 'Content-Type: application/json'
POST /api/canned-replies
5.2 Create Automated Reply
Request Fields
Field Type Example Description
name string About Us Rule display name
trigger string what do you do? Keyword or trigger phrase
match_criteria string contains Matching logic: contains, exact
response_type string text Content type (text)
response string We sell shoes and clothes Automated message sent back
cURL Request 
curl -X POST '{{base_url}}/api/canned-replies' \
  -H 'Authorization: Bearer YOUR_AUTHORIZATION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "About Us",
    "trigger": "what do you do?",
    "match_criteria": "contains",
    "response_type": "text",
    "response": "We offer official WhatsApp marketing and CRM solutions."
  }'
PUT /api/canned-replies/{uuid}
5.3 Update Automated Reply
cURL Request 
curl -X PUT '{{base_url}}/api/canned-replies/{uuid}' \
  -H 'Authorization: Bearer YOUR_AUTHORIZATION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "About Us Updated",
    "trigger": "pricing details",
    "match_criteria": "contains",
    "response_type": "text",
    "response": "Check out our plans here: https://waserve.com/pricing"
  }'
DELETE /api/canned-replies/{uuid}
5.4 Delete Automated Reply
cURL Request 
curl -X DELETE '{{base_url}}/api/canned-replies/{uuid}' \
  -H 'Authorization: Bearer YOUR_AUTHORIZATION_TOKEN' \
  -H 'Content-Type: application/json'

6. Messaging Endpoints

Send interactive text, media attachments, and official pre-approved Meta WhatsApp templates.

POST /api/send
6.1 Send Message (Text & Buttons)

Sends a standard text message with optional interactive buttons, header, and footer.

cURL Request 
curl -X POST '{{base_url}}/api/send' \
  -H 'Authorization: Bearer YOUR_AUTHORIZATION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone": "+19680825846",
    "message": "Hello John, your order has been received!",
    "header": "Order Update",
    "footer": "WAServe Notification",
    "buttons": [
      {"id": "btn_1", "title": "Track Order"},
      {"id": "btn_2", "title": "Support"}
    ]
  }'
POST /api/send/media
6.2 Send Media Content

Sends images, PDF documents, or videos to a recipient via direct public URL.

cURL Request 
curl -X POST '{{base_url}}/api/send/media' \
  -H 'Authorization: Bearer YOUR_AUTHORIZATION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone": "+19680825846",
    "media_type": "image",
    "media_url": "https://images.pexels.com/photos/276267/pexels-photo-276267.jpeg",
    "caption": "Check out your custom invoice preview",
    "file_name": "Invoice-INV-2026.pdf"
  }'
POST /api/send/template
6.3 Send WhatsApp Template

Sends a pre-approved Meta WhatsApp template message with dynamic parameters.

cURL Request 
curl -X POST '{{base_url}}/api/send/template' \
  -H 'Authorization: Bearer YOUR_AUTHORIZATION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "phone": "+19680825846",
  "template": {
    "name": "order_confirmation",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "John Doe"
          },
          {
            "type": "text",
            "text": "#ORD-9842"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "0",
        "parameters": [
          {
            "type": "payload",
            "payload": "TRACK_ORDER"
          }
        ]
      }
    ]
  }
}'

7. Multi-Language SDK Samples

Ready-to-use boilerplate code for popular backend technologies (PHP, Node.js, Python, Java, Ruby).

PHP (Guzzle) 
<?php
use GuzzleHttp\Client;

$client = new Client();
$response = $client->post('https://app.waserve.com/api/send', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_AUTHORIZATION_TOKEN',
        'Content-Type'  => 'application/json',
    ],
    'json' => [
        'phone'   => '+19680825846',
        'message' => 'Hello John, welcome to WAServe!',
    ],
]);

echo $response->getBody();
Node.js (Axios) 
const axios = require('axios');

async function sendWhatsAppMessage() {
  const response = await axios.post(
    'https://app.waserve.com/api/send',
    {
      phone: '+19680825846',
      message: 'Hello John, welcome to WAServe!'
    },
    {
      headers: {
        Authorization: 'Bearer YOUR_AUTHORIZATION_TOKEN',
        'Content-Type': 'application/json'
      }
    }
  );

  console.log(response.data);
}

sendWhatsAppMessage();
Python (Requests) 
import requests

url = 'https://app.waserve.com/api/send'
headers = {
    'Authorization': 'Bearer YOUR_AUTHORIZATION_TOKEN',
    'Content-Type': 'application/json'
}
payload = {
    'phone': '+19680825846',
    'message': 'Hello John, welcome to WAServe!'
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
Java (OkHttp) 
import okhttp3.*;

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(
    "{\"phone\":\"+19680825846\",\"message\":\"Hello John, welcome to WAServe!\"}", 
    mediaType
);

Request request = new Request.Builder()
    .url("https://app.waserve.com/api/send")
    .post(body)
    .addHeader("Authorization", "Bearer YOUR_AUTHORIZATION_TOKEN")
    .addHeader("Content-Type", "application/json")
    .build();

try (Response response = client.newCall(request).execute()) {
    System.out.println(response.body().string());
}
Ruby (Net::HTTP) 
require 'uri'
require 'net/http'
require 'json'

uri = URI('https://app.waserve.com/api/send')
req = Net::HTTP::Post.new(uri)
req['Authorization'] = 'Bearer YOUR_AUTHORIZATION_TOKEN'
req['Content-Type'] = 'application/json'
req.body = {
  phone: '+19680825846',
  message: 'Hello John, welcome to WAServe!'
}.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(req)
end

puts res.body

8. Testing & Production Checklist

Verify these critical items before deploying your WhatsApp messaging integration to live production.

Recommended Test Sequence

Step Action What to Verify
Step 1 Verify authentication Call GET /api/contacts with your Bearer token. Verify HTTP 200 OK.
Step 2 Create test record Call POST /api/contacts and store the returned uuid.
Step 3 Update test record Call PUT /api/contacts/{uuid} and confirm fields update.
Step 4 Exercise messaging Send a test text message to your verified WhatsApp number.
Step 5 Clean up Delete test records with DELETE /api/contacts/{uuid}.

Client Handoff Checklist

Production base URL is confirmed (https://app.waserve.com).
Bearer token has been generated and stored in a secure secret store.
Phone numbers use E.164 international format (e.g. +919876543210).
Media URLs are direct, HTTPS, and publicly accessible.
Template names, language codes, and component indexes match approved Meta templates.
Error handlers log status codes without logging sensitive tokens or recipient messages.
Start Integrating Now