SocioAPI SDK for WhatsApp Automation

Easily integrate WhatsApp automation and messaging features into your Node.js application using the SocioAPI SDK.

📦 Installation

npm install @socioapi/socioapi
# or
yarn add @socioapi/socioapi

🧠 Overview The @socioapi/socioapi SDK allows you to interact with WhatsApp via SocioAPI’s robust backend API. It supports:

Connecting sessions via QR or phone number

Fetching contact lists

Sending WhatsApp stories (text, image, video, audio)

Sending direct messages (text, image, video, audio, document)

⚙️ Environment Setup Make sure to set the following environment variables before using the SDK:

SOCIOAPIKEY=your_api_key
SOCIOAPISECRET=your_api_secret
SOCIOAPIENV=production

🚀 Usage Example

import Socioapi from "@socioapi/socioapi";
import { environmentType } from "@socioapi/socioapi/src/whatsapp/interfaces/IWhatsappApi.interface";

const { whatsapp } = new Socioapi(
    process.env.SOCIOAPIKEY!,
    process.env.SOCIOAPISECRET!,
    process.env.SOCIOAPIENV as environmentType
);

🧩 API Reference 📱 1. Session Management Connect via QR

await whatsapp.session.connect(sessionId, "qr");

sessionId: Unique string to identify the session.

"qr": Triggers QR-based authentication.

📌 The SDK returns the QR code string and connection state.

Connect via Phone Number

await whatsapp.session.connect(sessionId, "phoneNumber", "2348100023411");

phoneNumber: Your registered WhatsApp phone number in international format.

👥 2. Fetch Contacts

await whatsapp.contact.getContacts(sessionId, 0, 10000);

Retrieves a paginated list of WhatsApp contacts.

📚 Story Messaging You can post stories (status updates) to selected contacts.

✏️ Send Text Story

await whatsapp.story.sendTextStory(sessionId, {
    message: {
        text: "Hello from Kufuli!",
    },
    options: {
        contactList: ["[email protected]"],
        font: 1,
        backgroundColor: "#000000",
    },
});

🖼️ Send Image Story

await whatsapp.story.sendImageStory(sessionId, {
    message: {
        image: {
            url: "https://example.com/image.jpg",
        },
        caption: "Check this out!",
    },
    options: {
        contactList: ["[email protected]"],
    },
});

🎥 Send Video Story

await whatsapp.story.sendVideoStory(sessionId, {
    message: {
        video: {
            url: "https://example.com/video.mp4",
        },
        caption: "Watch this!",
    },
    options: {
        contactList: ["[email protected]"],
    },
});

🔊 Send Audio Story

await whatsapp.story.sendAudioStory(sessionId, {
    message: {
        audio: {
            url: "https://example.com/audio.wav",
        },
    },
    options: {
        contactList: ["[email protected]"],
        backgroundColor: "#000000",
    },
});

💬 Direct Messaging You can send direct WhatsApp messages of various media types.

📃 Base Message Format

{
jid: "[email protected]",
type: "number",
message: {
text/image/video/audio/document: {...}
}
}

📝 Send Text Message

await whatsapp.message.sendTextMessage(sessionId, {
    jid: "[email protected]",
    type: "number",
    message: {
        text: "Hello!",
    },
});

🖼️ Send Image Message

await whatsapp.message.sendImageMessage(sessionId, {
    jid: "[email protected]",
    type: "number",
    message: {
        image: {
            url: "https://example.com/image.jpg",
        },
    },
});

🎞️ Send Video Message

await whatsapp.message.sendVideoMessage(sessionId, {
    jid: "[email protected]",
    type: "number",
    message: {
        video: {
            url: "https://example.com/video.mp4",
        },
    },
});

🔊 Send Audio Message

await whatsapp.message.sendAudioMessage(sessionId, {
    jid: "[email protected]",
    type: "number",
    message: {
        audio: {
            url: "https://example.com/audio.wav",
        },
    },
});

📄 Send Document Message

await whatsapp.message.sendDocumentMessage(sessionId, {
    jid: "[email protected]",
    type: "number",
    message: {
        document: {
            url: "https://example.com/file.pdf",
        },
    },
    options: {
        mimetype: "application/pdf",
    },
});

🧪 Example: Full Action Handler Here’s a unified function that handles all actions for reference:

async function main(sessionId: string, action: ActionType) {
// ... fetch env variables & instantiate SDK
switch (action) {
case "connect_qr":
await whatsapp.session.connect(sessionId, "qr");
break;
case "send_text_message":
await whatsapp.message.sendTextMessage(sessionId, { ... });
break;
// other cases...
}
}

🧯 Error Handling Each SDK call may throw an error if:

API keys are missing or invalid

Session ID is incorrect

Action payloads are malformed

Wrap calls in try/catch blocks:

try {
    await whatsapp.session.connect("mysession", "qr");
} catch (error) {
    console.error("Error connecting session:", error);
}

📞 Support For issues or help using the SDK, contact the Kufuli/SocioAPI team or open an issue on GitHub.

🪪 License MIT License. See LICENSE for details.