Africa's Talking MCP by usefulapi

The Africa's Talking app balance (SMS/airtime wallet), e.g. {"balance": "KES 1250.0000"}. The sandbox app has no balance. GET /version1/user.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Fetch incoming SMS received on your shortcodes/numbers, oldest first, in batches (default 25 per call). Pass last_received_id (0 for the first call, then `next_last_received_id` from the previous reply) to move through them; `has_more` stays true while a call returns messages, so keep calling until `count` is 0. Optional shortcode and keyword filters. GET /version1/messaging.

{
  "type": "object",
  "properties": {
    "last_received_id": {
      "description": "Id of the last message already read (default 0 = from the start).",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "short_code": {
      "description": "Only messages sent to this shortcode / number.",
      "type": "string",
      "maxLength": 20
    },
    "keyword": {
      "description": "Only messages that start with this keyword.",
      "type": "string",
      "maxLength": 50
    },
    "limit": {
      "description": "Most messages to return per call (default 25); `has_more` says if more are waiting.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: send one text message to up to 100 phone numbers. Spends account credit and delivers to real phones (the sandbox app only reaches the simulator). Needs confirm=true after the user approved the recipients and text. Returns the vendor's per-recipient status (statusCode 101 = sent), message ids and cost. Never retried. POST /version1/messaging.

{
  "type": "object",
  "properties": {
    "to": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^\\+[1-9]\\d{6,14}$"
      },
      "description": "Recipients in international format, e.g. +254711000000 (max 100)."
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1600,
      "description": "The SMS text (1-1600 characters; long texts are split into several billed parts)."
    },
    "sender_id": {
      "description": "Approved alphanumeric sender ID, shortcode or long-code number (e.g. +27... in South Africa); omit to use the account default.",
      "type": "string",
      "pattern": "^(?:\\+\\d{6,16}|[A-Za-z0-9 ._-]{1,16})$"
    },
    "confirm": {
      "type": "boolean",
      "description": "Must be true. Set it only after the user has explicitly approved this exact send (recipients, text/amount); it spends account credit."
    }
  },
  "required": [
    "to",
    "message",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: top up mobile airtime for up to 25 phone numbers. Spends account credit immediately and cannot be reversed. Needs confirm=true after the user approved each number and amount. Amounts are in the given ISO currency (e.g. KES, UGX, TZS). Pass an idempotency_key to make a retry safe. Returns per-number status and requestId (use africastalking_find_airtime_transaction to follow up). POST /version1/airtime/send.

{
  "type": "object",
  "properties": {
    "recipients": {
      "minItems": 1,
      "maxItems": 25,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "phone_number": {
            "type": "string",
            "pattern": "^\\+[1-9]\\d{6,14}$"
          },
          "currency_code": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          },
          "amount": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 1000000,
            "description": "Amount of airtime in that currency."
          }
        },
        "required": [
          "phone_number",
          "currency_code",
          "amount"
        ]
      }
    },
    "idempotency_key": {
      "description": "Optional unique key (8-100 chars) for this send; the same key makes Africa's Talking ignore a duplicate request.",
      "type": "string",
      "pattern": "^[A-Za-z0-9._:-]{8,100}$"
    },
    "confirm": {
      "type": "boolean",
      "description": "Must be true. Set it only after the user has explicitly approved this exact send (recipients, text/amount); it spends account credit."
    }
  },
  "required": [
    "recipients",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Look up an airtime transaction by its transaction id (the requestId / ATPid_... from a send reply): status, amount, destination and discount. GET /query/transaction/find.

{
  "type": "object",
  "properties": {
    "transaction_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "The transaction id, e.g. ATPid_..."
    }
  },
  "required": [
    "transaction_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: send mobile data bundles to up to 25 phone numbers from your Africa's Talking data wallet. Spends wallet credit and cannot be reversed. Needs confirm=true after the user approved each number and bundle. product_name is your data product (created in the Africa's Talking dashboard). Pass an idempotency_key to make a retry safe. Returns per-number status and transactionId (see africastalking_find_mobile_data_transaction). POST bundles /mobile/data/request.

{
  "type": "object",
  "properties": {
    "product_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Name of your mobile data product in the Africa's Talking dashboard."
    },
    "recipients": {
      "minItems": 1,
      "maxItems": 25,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "phone_number": {
            "type": "string",
            "pattern": "^\\+[1-9]\\d{6,14}$"
          },
          "quantity": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 100000,
            "description": "Bundle size in `unit`."
          },
          "unit": {
            "type": "string",
            "enum": [
              "MB",
              "GB"
            ]
          },
          "validity": {
            "type": "string",
            "enum": [
              "Day",
              "Week",
              "BiWeek",
              "Month",
              "Quarterly"
            ]
          },
          "metadata": {
            "description": "Optional key-value labels stored with the transaction.",
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "string"
            }
          }
        },
        "required": [
          "phone_number",
          "quantity",
          "unit",
          "validity"
        ]
      }
    },
    "idempotency_key": {
      "description": "Optional unique key (8-100 chars) for this send; the same key makes Africa's Talking ignore a duplicate request.",
      "type": "string",
      "pattern": "^[A-Za-z0-9._:-]{8,100}$"
    },
    "confirm": {
      "type": "boolean",
      "description": "Must be true. Set it only after the user has explicitly approved this exact send (recipients, text/amount); it spends account credit."
    }
  },
  "required": [
    "product_name",
    "recipients",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Look up a mobile data transaction by its transactionId (from a send reply): status, product, destination and cost. GET bundles /query/transaction/find.

{
  "type": "object",
  "properties": {
    "transaction_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "The mobile data transactionId."
    }
  },
  "required": [
    "transaction_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The balance of the mobile data wallet, e.g. {"status": "Success", "balance": "KES 500.0000"}. GET bundles /query/wallet/balance.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: place an outbound voice call from one of your Africa's Talking numbers to up to 10 phone numbers. The call is billed and rings real phones; what is said is decided by the voice callback URL configured for the number in the dashboard. Needs confirm=true after the user approved the numbers. Live apps only (the sandbox has no voice service). Returns a per-number queue status. POST voice /call.

{
  "type": "object",
  "properties": {
    "call_from": {
      "type": "string",
      "pattern": "^\\+[1-9]\\d{6,14}$",
      "description": "Your Africa's Talking voice number to call from (international format)."
    },
    "call_to": {
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^\\+[1-9]\\d{6,14}$"
      },
      "description": "Numbers to call (max 10)."
    },
    "client_request_id": {
      "description": "Optional label passed back to your voice callback URL as clientRequestId.",
      "type": "string",
      "pattern": "^[A-Za-z0-9._:-]{1,64}$"
    },
    "confirm": {
      "type": "boolean",
      "description": "Must be true. Set it only after the user has explicitly approved this exact send (recipients, text/amount); it spends account credit."
    }
  },
  "required": [
    "call_from",
    "call_to",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Number of outbound calls currently queued on each of your voice numbers. Live apps only. POST voice /queueStatus (a read: nothing is changed).

{
  "type": "object",
  "properties": {
    "phone_numbers": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^\\+[1-9]\\d{6,14}$"
      },
      "description": "Your Africa's Talking voice numbers to check."
    }
  },
  "required": [
    "phone_numbers"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}