Partner Messaging API Documentation

Overview

The Partner Messaging API allows third-party partners to integrate with our messaging platform to send messages across multiple channels, including WhatsApp.

Base URL: https://api-z5ldvuj2ma-as.a.run.app

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

x-api-key: your_api_key_here

To obtain an API key, contact your account manager or use the main platform dashboard.

Response Format

All API responses follow a consistent JSON structure for clarity and predictability.

Success Response

{
    "success": true,
    "data": { ... },
    "message": "Optional success message"
}

Error Response

{
    "success": false,
    "error": "Error description",
    "code": "ERROR_CODE"
}

All responses use standard HTTP status codes (200 for success, 4xx/5xx for errors).

Error Codes

The following table lists common error codes returned by the Partner Messaging API:

Code	Description
INVALID_REQUEST	Request structure is invalid
VALIDATION_ERROR	Request validation failed
ORG_NOT_FOUND	Organization not found
ORG_INACTIVE	Organization is not active
APP_NOT_FOUND	App not found
APP_INACTIVE	App is not active
INSUFFICIENT_CREDIT	Not enough credit balance
CHANNEL_CONFIG_NOT_FOUND	Channel configuration missing
CHANNEL_CREDENTIALS_NOT_FOUND	Channel credentials not configured
MESSAGE_NOT_FOUND	Message not found or access denied
INVALID_PAGINATION	Invalid pagination parameters

API Endpoints

1. Send Message

Send a message across supported channels such as WhatsApp or SMS.

Endpoint: POST /partner/message/send

WhatsApp Example

{
            "request": {
                "channel": "WHATSAPP",
                "to": "+1234567890",
                "from": "+1234567890",
                "templateId": "HXf8aa5a783ac6df54b1d28473f2de4c75",
                "templateVariables": { "1": "OTP_CODE" }
            }
        }

SMS Example

{
            "request": {
                "channel": "SMS",
                "to": "+1234567890",
                "senderId": "Pathomics",
                "templateId": "HXf8aa5a783ac6df54b1d28473f2de4c75",
                "templateVariables": { "1": "OTP_CODE" }
            }
        }

Success Response

{
            "success": true,
            "message": "Message sent successfully.",
            "data": {
                "messageId": "msg_123456789",
                "recipient": "+1234567890",
                "channel": "WHATSAPP",
                "status": "SENT",
                "cost": 0.12,
                "currency": "SGD"
            }
        }

Code Examples

Python Example

import requests, json
          
API_KEY = "your_api_key_here"
BASE_URL = "https://your-api-domain.com"

headers = {
"x-api-key": API_KEY,
"Content-Type": "application/json"
}

def send_sms(phone, message):
data = {"request": {"channel": "SMS", "to": phone, "content": message}}
res = requests.post(f"{BASE_URL}/partner/message/send", headers=headers, json=data)
return res.json()

result = send_sms("+1234567890", "Hello from API!")
print(result)

Node.js Example

const axios = require('axios');

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://your-api-domain.com';

const headers = { 'x-api-key': API_KEY, 'Content-Type': 'application/json' };

async function sendEmail(to, subject, htmlContent) {
const response = await axios.post(
    `${BASE_URL}/partner/message/send`,
    { request: { channel: 'EMAIL', to, subject, htmlContent } },
    { headers }
);
return response.data;
}

sendEmail('user@example.com', 'Test', '<h1>Hello</h1>').then(console.log);

Support

For technical questions, integration assistance, or issues with API usage, please reach out to our technical support team.

Email: technical@heysheep.sg

We aim to respond to all support inquiries within 24 hours during business days.

Changelog

Version 1.0 (Current)

Initial release with WhatsApp support
Message status tracking and credit balance management
Comprehensive filtering and pagination
Improved fallback message handling