Africa's Talking Node.js SDK

The WhatsApp service allows sending messages and managing templates.

Send WhatsApp Messages

• sendMessage({ body, waNumber, phoneNumber }): Sends a message to a recipient.

Parameters:

• waNumber (REQUIRED): The WhatsApp number associated with your account.
• phoneNumber (REQUIRED): The recipient's number.
• body: An object defining the message type:
  • Simple Text: { message: 'text' }
  • Media: { mediaType: 'Image'|'Video'|'Audio'|'Document'|'Voice', url: '...', caption: '...' }
  • Interactive List: Contains action (buttons, sections, rows, product_items), body, header, and footer.
  • Interactive Buttons: Contains action (buttons), body, header, and footer.
  • Template: { templateId: '...', headerValue: '...', bodyValues: [...] }

Manage Templates

• createTemplate({ component, waNumber, name, language, category }): Creates a new message template.
  • waNumber (REQUIRED): Your account's WhatsApp number.
  • name (REQUIRED): Unique template name.
  • language (REQUIRED): ISO 639-1 code.
  • category: MARKETING, UTILITY, or AUTHENTICATION.
  • components: Object defining header, body, footer, and buttons (including types like PHONE_NUMBER, URL, FLOW, COPY_CODE, or QUICK_REPLY).

The MobileData service manages mobile data bundles.

Send Mobile Data

• send({ productName, recipients }): Sends data bundles to recipients.

Parameters:

• productName: The application's product name.
• recipients (REQUIRED): An array of objects containing:
  • phoneNumber (REQUIRED): Recipient's phone number.
  • quantity (REQUIRED): Numeric value for the amount of data.
  • unit (REQUIRED): Units (MB or GB).
  • validity (REQUIRED): Period of validity (Day, Week, BiWeek, Month, or Quarterly).
  • metadata (REQUIRED): A JSON object for associated metadata.

Other Methods

• findTransaction({ transactionId }): Find a specific mobile data transaction.
• fetchWalletBalance(): Fetch the mobile data product balance.

await mobileData.send({
  productName: 'MyDataApp',
  recipients: [{
    phoneNumber: '+234xxxxxxxxxx',
    quantity: 1,
    unit: 'GB',
    validity: 'Month',
    metadata: { userId: '123' }
  }]
});

The SMS service allows you to send standard messages, premium messages, and manage subscriptions. All methods are asynchronous and phone numbers must use the international format (e.g., +234xxxxxxxx).

Standard SMS

• send({ to, senderId, message, enqueue }): Send an SMS to a single number or an array of numbers.
• send([{ to, senderId, message, enqueue }]): Send multiple SMSes using an array of objects.

Parameters:

• to (REQUIRED): Recipient phone number or array of numbers.
• senderId: Registered shortcode or alphanumeric ID.
• message (REQUIRED): The SMS content.
• enqueue: Boolean. If true, messages are delivered without waiting for telco acknowledgement.

Premium SMS

• sendPremium({ to, from, message, enqueue, keyword, linkId, retryDurationInHours }): Send premium SMS.
  • keyword: Your premium product keyword.
  • linkId: Forwarded to your application when a user sends a message.
  • retryDurationInHours: Number of hours to retry subscription messages if undelivered.
• fetchMessages({ lastReceivedId }): Manually retrieve messages. lastReceivedId defaults to 0.
• fetchSubscription({ shortCode, keyword, lastReceivedId }): Fetch premium subscription data. shortCode and keyword are REQUIRED.
• createSubscription({ shortCode, keyword, phoneNumber }): Create a premium subscription. shortCode, keyword, and phoneNumber are REQUIRED.

// Example: Sending a single SMS
await sms.send({
  to: '+234xxxxxxxxxx',
  message: 'Hello from Africa\'s Talking!',
  senderId: 'MY_SENDER_ID'
});

The SMS service allows you to manage user subscriptions to specific keywords and shortcodes (often used for opt-in/opt-out flows).

• createSubscription(params): Registers a phone number to a shortCode and keyword.
• fetchSubscription(params): Retrieves active subscriptions. Can be filtered by lastReceivedId to paginate or fetch new updates.
• deleteSubscription(params): Removes a subscription for a specific phoneNumber, shortCode, and keyword.

Subscription Parameter Requirements:

• shortCode: The shortcode string (required).
• keyword: The keyword string (required).
• phoneNumber: The recipient's phone number (required for create/delete).
• lastReceivedId: Used in fetchSubscription to track progress.

// Create a subscription
await sms.createSubscription({
  shortCode: '12345',
  keyword: 'JOIN',
  phoneNumber: '2547XXXXXXXX'
});

// Delete a subscription
await sms.deleteSubscription({
  shortCode: '12345',
  keyword: 'JOIN',
  phoneNumber: '2547XXXXXXXX'
});