Send Contact Message

Share one or more contact cards with a WhatsApp recipient. Each contact is delivered as a complete card the recipient can save to their address book.

Endpoint

POST /whatsapp/send-contact/:instance

• :instance: The name of your WhatsApp instance (e.g., my-bot).

Request Body

Parameter	Type	Required	Description
recipient	string	Yes	The recipient's WhatsApp number with country code (e.g., 254123456789) or the full sender address from a webhook (e.g., 123456789012345@lid or [email protected]). Send @lid addresses exactly as received; do not format them or remove the suffix.
contact	array	Yes	One or more contacts to share. See the contact fields below.

Contact Fields

Field	Type	Required	Description
fullName	string	Yes	The contact's full name.
phoneNumber	string	Yes	The contact's phone number in international format (e.g., +254700111222). Spaces, dashes, parentheses, and a leading + are stripped automatically. ChatBreez generates the contact's WhatsApp ID from this number — no separate field is needed.
organization	string	No	A company or organization name.
email	string	No	The contact's email address.
url	string	No	A website associated with the contact.

Example Payload — Single Contact

{
  "recipient": "254123456789",
  "contact": [
    {
      "fullName": "Jane Smith",
      "phoneNumber": "+254700111222",
      "organization": "ChatBreez Ltd",
      "email": "[email protected]",
      "url": "https://example.com"
    }
  ]
}

Example Payload — Multiple Contacts

Add more objects to the contact array to share several cards in one message:

{
  "recipient": "254123456789",
  "contact": [
    {
      "fullName": "Jane Smith",
      "phoneNumber": "+254700111222"
    },
    {
      "fullName": "John Doe",
      "phoneNumber": "+254700333444"
    }
  ]
}

Examples

cURL

curl -X POST https://api.chatbreez.com/whatsapp/send-contact/{instance} \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "254123456789",
    "contact": [
      {
        "fullName": "Jane Smith",
        "phoneNumber": "+254700111222",
        "organization": "ChatBreez Ltd",
        "email": "[email protected]",
        "url": "https://example.com"
      }
    ]
  }'

JavaScript

const axios = require('axios');

const sendContact = async () => {
  try {
    const response = await axios.post('https://api.chatbreez.com/whatsapp/send-contact/{instance}', {
      recipient: '254123456789',
      contact: [
        {
          fullName: 'Jane Smith',
          phoneNumber: '+254700111222',
          organization: 'ChatBreez Ltd',
          email: '[email protected]',
          url: 'https://example.com'
        }
      ]
    }, {
      headers: {
        'X-API-Key': 'your_api_key'
      }
    });
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
};

sendContact();

Python

import requests

url = "https://api.chatbreez.com/whatsapp/send-contact/{instance}"

payload = {
    "recipient": "254123456789",
    "contact": [
        {
            "fullName": "Jane Smith",
            "phoneNumber": "+254700111222",
            "organization": "ChatBreez Ltd",
            "email": "[email protected]",
            "url": "https://example.com"
        }
    ]
}

headers = {
    "Content-Type": "application/json",
    "X-API-Key": "your_api_key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.chatbreez.com/whatsapp/send-contact/{instance}"

	payload := map[string]interface{}{
		"recipient": "254123456789",
		"contact": []map[string]interface{}{
			{
				"fullName":     "Jane Smith",
				"phoneNumber":  "+254700111222",
				"organization": "ChatBreez Ltd",
				"email":        "[email protected]",
				"url":          "https://example.com",
			},
		},
	}
	body, _ := json.Marshal(payload)

	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(body))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-API-Key", "your_api_key")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()

	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://api.chatbreez.com/whatsapp/send-contact/{instance}";
        String json = """
            {
              "recipient": "254123456789",
              "contact": [
                {
                  "fullName": "Jane Smith",
                  "phoneNumber": "+254700111222",
                  "organization": "ChatBreez Ltd",
                  "email": "[email protected]",
                  "url": "https://example.com"
                }
              ]
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/json")
            .header("X-API-Key", "your_api_key")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

PHP

<?php

$url = 'https://api.chatbreez.com/whatsapp/send-contact/{instance}';

$payload = json_encode([
    'recipient' => '254123456789',
    'contact' => [
        [
            'fullName' => 'Jane Smith',
            'phoneNumber' => '+254700111222',
            'organization' => 'ChatBreez Ltd',
            'email' => '[email protected]',
            'url' => 'https://example.com',
        ],
    ],
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: your_api_key',
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Response

{
  "message": "Contact message queued for delivery.",
  "messageId": "3EB0C767D097B7C7C030"
}

Keep the messageId if you need to reference the message later when investigating a delivery.

Common Errors

Errors are returned as JSON in this shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "contact: At least one contact is required",
    "correlationId": "abc123-def456-ghi789"
  }
}

Status	Code	Meaning
400	VALIDATION_ERROR	The request body is invalid, a contact field is missing, or the recipient is not registered on WhatsApp.
401	UNAUTHORIZED	Missing or invalid API key.
403	FORBIDDEN	Your account is deactivated. Contact support to reactivate it.
404	NOT_FOUND	The instance does not exist.
409	CONFLICT	The instance is not connected to WhatsApp. Reconnect it and try again.
502	UPSTREAM_ERROR	WhatsApp did not acknowledge the message. Try again shortly.
500	INTERNAL_SERVER_ERROR	An unexpected error occurred on our side. Try again shortly.

Next Steps

• Send Text Messages
• Send Media Messages — images, videos, documents, and audio files
• Send Audio Messages — audio attachments and voice notes
• Send Location Messages — share a location pin
• Send Poll Messages — create polls with up to ten options
• Check Instance Status