AI Agent Integration

Integrate Ping's notification APIs with AI agents to send SMS, WhatsApp, and email messages programmatically. Supports REST API (universal), Model Context Protocol (Claude Desktop), OpenClawd (open-source agents), and Google WebMCP (browser-based agents).

RESTUniversal

REST API (All Agents)

Any AI agent with HTTP request capabilities can use Ping's REST API directly. This is the most universal integration method.

Common use cases

OTP delivery - Send verification codes via SMS or WhatsApp
Notification workflows - Alert users about events
Bulk campaigns - Send marketing messages to customer lists
Transactional emails - Order confirmations, receipts, password resets

Authentication

Use API keys for agent-to-server authentication:

Create an API key in your Ping dashboard
Store the key in environment variables
Include X-Ping-Api-Key header in all requests

Quick start

import os
import requests

def send_notification(phone, message):
    """Send SMS notification via Ping API."""
    response = requests.post(
        'https://api.ping.co.zw/v1/notification/api/sms/send',
        headers={
            'X-Ping-Api-Key': os.getenv('PING_API_KEY'),
            'Content-Type': 'application/json'
        },
        json={
            'to_phone': phone,
            'message': message
        }
    )
    return response.json()

# Agent can call this function
result = send_notification('+263771234567', 'Your OTP is 482910')
print(result)

Environment variables

.env

PING_API_KEY=pk_live_your_api_key_here

Available endpoints

Name
SMS
Description
POST /v1/notification/api/sms/send
Name
WhatsApp
Description
POST /v1/notification/api/whatsapp/send
Name
Email
Description
POST /v1/notification/api/email/send
Name
Bulk
Description
All endpoints support arrays for bulk sending

Documentation: See the SMS, WhatsApp, and Email pages for complete API reference and examples.

MCPClaude Desktop

Model Context Protocol (MCP)

Model Context Protocol (MCP) enables Claude Desktop to access external tools and services. Create an MCP server to give Claude the ability to send notifications through Ping.

What is MCP?

MCP is a protocol developed by Anthropic that allows AI models to interact with external systems through standardized tool definitions. An MCP server exposes functions (tools) that Claude can call.

Creating a Ping MCP Server

1. Install MCP SDK:

npm install @anthropic-ai/sdk

2. Create the MCP server (ping-mcp-server.js):

const { MCPServer } = require('@anthropic-ai/sdk')

const server = new MCPServer({
  name: 'ping-notifications',
  version: '1.0.0',
})

// Define the send_sms tool
server.addTool({
  name: 'send_sms',
  description: 'Send an SMS message via Ping',
  parameters: {
    type: 'object',
    properties: {
      to_phone: {
        type: 'string',
        description: 'Recipient phone number in E.164 format (e.g., +263771234567)',
      },
      message: {
        type: 'string',
        description: 'SMS message content',
      },
    },
    required: ['to_phone', 'message'],
  },
  handler: async ({ to_phone, message }) => {
    const response = await fetch(
      'https://api.ping.co.zw/v1/notification/api/sms/send',
      {
        method: 'POST',
        headers: {
          'X-Ping-Api-Key': process.env.PING_API_KEY,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ to_phone, message }),
      }
    )
    return await response.json()
  },
})

// Start the server
server.start()

3. Configure Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "ping": {
      "command": "node",
      "args": ["/path/to/ping-mcp-server.js"],
      "env": {
        "PING_API_KEY": "pk_live_your_api_key"
      }
    }
  }
}

4. Restart Claude Desktop

Claude can now send SMS messages through your MCP server.

Using the MCP server

Once configured, you can ask Claude:

"Send an SMS to +263771234567 with the message 'Your appointment is tomorrow at 2pm'"

Claude will:

Recognize the intent to send SMS
Call the send_sms tool via MCP
Return the result to you

Additional tools to add

// WhatsApp tool
server.addTool({
  name: 'send_whatsapp',
  description: 'Send WhatsApp message via Ping',
  parameters: { /* ... */ },
  handler: async ({ to_phone, message }) => {
    // Call Ping WhatsApp API
  },
})

// Email tool
server.addTool({
  name: 'send_email',
  description: 'Send email via Ping',
  parameters: { /* ... */ },
  handler: async ({ to, subject, html }) => {
    // Call Ping Email API
  },
})

Learn more: Visit MCP documentation for full MCP server development guide.

OpenClawdOpen Source Agents

OpenClawd

OpenClawd is an open-source framework for building AI agents with tool-calling capabilities. Integrate Ping using the REST API approach.

Integration approach

OpenClawd agents use Python-based tool definitions. Define Ping notification tools as functions that agents can call.

Example: SMS tool for OpenClawd

import os
import requests
from openclawd import tool

@tool(
    name="send_sms",
    description="Send an SMS message via Ping",
    parameters={
        "to_phone": "Recipient phone number in E.164 format",
        "message": "SMS message content"
    }
)
def send_sms(to_phone: str, message: str) -> dict:
    """Send SMS via Ping API."""
    response = requests.post(
        'https://api.ping.co.zw/v1/notification/api/sms/send',
        headers={
            'X-Ping-Api-Key': os.getenv('PING_API_KEY'),
            'Content-Type': 'application/json'
        },
        json={'to_phone': to_phone, 'message': message}
    )
    return response.json()

# Agent can now call send_sms as a tool

Example: Email tool for OpenClawd

@tool(
    name="send_email",
    description="Send an email via Ping",
    parameters={
        "to": "Recipient email address",
        "subject": "Email subject",
        "html": "Email HTML content"
    }
)
def send_email(to: str, subject: str, html: str) -> dict:
    """Send email via Ping API."""
    from_address = os.getenv('PING_FROM_EMAIL', '[email protected]')

    response = requests.post(
        'https://api.ping.co.zw/v1/notification/api/email/send',
        headers={
            'X-Ping-Api-Key': os.getenv('PING_API_KEY'),
            'Content-Type': 'application/json'
        },
        json={
            'from': from_address,
            'to': [to],
            'subject': subject,
            'html': html
        }
    )
    return response.json()

Configuration

.env

PING_API_KEY=pk_live_your_api_key
PING_FROM_EMAIL=[email protected]

Usage in agent

from openclawd import Agent

# Create agent with Ping tools
agent = Agent(
    tools=[send_sms, send_email],
    instructions="You can send SMS and emails via Ping"
)

# Agent can now send notifications
response = agent.run(
    "Send an OTP code 482910 via SMS to +263771234567"
)

Best practice: Wrap API calls in try/except blocks and return descriptive error messages to help the agent understand failures.

WebMCPBrowser-Based Agents

Google WebMCP

Google WebMCP enables browser-based AI agents (like Gemini) to interact with web services. Expose Ping API endpoints to WebMCP-compatible agents.

What is WebMCP?

WebMCP is a protocol that allows browser-based AI agents to call external APIs through a standardized interface. It's designed for agents running in web applications.

Creating a WebMCP endpoint

Create a server-side endpoint that exposes Ping functionality:

// server.js (Node.js/Express)
const express = require('express')
const app = express()

app.use(express.json())

// WebMCP endpoint for sending SMS
app.post('/webmcp/ping/send-sms', async (req, res) => {
  const { to_phone, message } = req.body

  // Validate request
  if (!to_phone || !message) {
    return res.status(400).json({
      error: 'Missing required fields: to_phone, message'
    })
  }

  try {
    // Call Ping API
    const response = await fetch(
      'https://api.ping.co.zw/v1/notification/api/sms/send',
      {
        method: 'POST',
        headers: {
          'X-Ping-Api-Key': process.env.PING_API_KEY,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ to_phone, message }),
      }
    )

    const result = await response.json()
    res.json(result)
  } catch (error) {
    res.status(500).json({ error: error.message })
  }
})

app.listen(3000, () => {
  console.log('WebMCP server running on port 3000')
})

WebMCP manifest

Define available tools in a manifest file:

{
  "name": "Ping Notifications",
  "version": "1.0.0",
  "tools": [
    {
      "name": "send_sms",
      "description": "Send SMS message via Ping",
      "endpoint": "/webmcp/ping/send-sms",
      "method": "POST",
      "parameters": {
        "to_phone": {
          "type": "string",
          "description": "Phone number in E.164 format",
          "required": true
        },
        "message": {
          "type": "string",
          "description": "SMS message content",
          "required": true
        }
      }
    }
  ]
}

Security considerations

CORS configuration:

const cors = require('cors')

// Only allow your frontend domain
app.use(cors({
  origin: 'https://yourdomain.com',
  credentials: true
}))

API key protection:

Never expose Ping API keys to the browser
Keep keys server-side only
Add authentication to your WebMCP endpoints
Rate limit requests to prevent abuse

Example with auth:

app.post('/webmcp/ping/send-sms',
  authenticateUser, // Your auth middleware
  async (req, res) => {
    // Only authenticated users can send
    // ...
  }
)

Important: WebMCP endpoints are server-side proxies. Never call Ping API directly from browser JavaScript - always proxy through your secure backend.

Comparison

Which integration method should I use?

Integration	Best For	Complexity	Setup Time
REST API	All agents, maximum flexibility	Low	5 minutes
MCP	Claude Desktop users	Medium	30 minutes
OpenClawd	Open-source Python agents	Medium	20 minutes
WebMCP	Browser-based agents (Gemini)	High	1-2 hours

Recommendation

Starting out? Use REST API directly - it's universal and simple
Using Claude Desktop? Build an MCP server for seamless integration
Building custom agents? Use REST API with your agent framework
Need browser integration? Create WebMCP proxy endpoints

Need help?

REST API documentation: See SMS, WhatsApp, Email pages
Authentication guide: See Authentication page
Rate limiting: See Rate Limiting page
Support: [email protected]