npm package: @socioapi/socioapi
Description: Official Socioapi API package Node.js
Author: aderibigbeganiu
Latest version: 0.0.8

# SocioAPI SDK for WhatsApp Automation

![npm version](https://img.shields.io/npm/v/@socioapi/socioapi)  
Easily integrate WhatsApp automation and messaging features into your Node.js application using the SocioAPI SDK.

## 📦 Installation

```bash
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:

```env
SOCIOAPIKEY=your_api_key
SOCIOAPISECRET=your_api_secret
SOCIOAPIENV=production
```

🚀 Usage Example

```ts
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

```ts
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

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

phoneNumber: Your registered WhatsApp phone number in international format.

👥 2. Fetch Contacts

```ts
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

```ts
await whatsapp.story.sendTextStory(sessionId, {
    message: {
        text: "Hello from Kufuli!",
    },
    options: {
        contactList: ["2349000702700@s.whatsapp.net"],
        font: 1,
        backgroundColor: "#000000",
    },
});
```

🖼️ Send Image Story

```ts
await whatsapp.story.sendImageStory(sessionId, {
    message: {
        image: {
            url: "https://example.com/image.jpg",
        },
        caption: "Check this out!",
    },
    options: {
        contactList: ["2349000702700@s.whatsapp.net"],
    },
});
```

🎥 Send Video Story

```ts
await whatsapp.story.sendVideoStory(sessionId, {
    message: {
        video: {
            url: "https://example.com/video.mp4",
        },
        caption: "Watch this!",
    },
    options: {
        contactList: ["2349000702700@s.whatsapp.net"],
    },
});
```

🔊 Send Audio Story

```ts
await whatsapp.story.sendAudioStory(sessionId, {
    message: {
        audio: {
            url: "https://example.com/audio.wav",
        },
    },
    options: {
        contactList: ["2349000702700@s.whatsapp.net"],
        backgroundColor: "#000000",
    },
});
```

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

📃 Base Message Format

```ts
{
jid: "2348100023411@s.whatsapp.net",
type: "number",
message: {
text/image/video/audio/document: {...}
}
}
```

📝 Send Text Message

```ts
await whatsapp.message.sendTextMessage(sessionId, {
    jid: "2348100023411@s.whatsapp.net",
    type: "number",
    message: {
        text: "Hello!",
    },
});
```

🖼️ Send Image Message

```ts
await whatsapp.message.sendImageMessage(sessionId, {
    jid: "2348100023411@s.whatsapp.net",
    type: "number",
    message: {
        image: {
            url: "https://example.com/image.jpg",
        },
    },
});
```

🎞️ Send Video Message

```ts
await whatsapp.message.sendVideoMessage(sessionId, {
    jid: "2348100023411@s.whatsapp.net",
    type: "number",
    message: {
        video: {
            url: "https://example.com/video.mp4",
        },
    },
});
```

🔊 Send Audio Message

```ts
await whatsapp.message.sendAudioMessage(sessionId, {
    jid: "2348100023411@s.whatsapp.net",
    type: "number",
    message: {
        audio: {
            url: "https://example.com/audio.wav",
        },
    },
});
```

📄 Send Document Message

```ts
await whatsapp.message.sendDocumentMessage(sessionId, {
    jid: "2348100023411@s.whatsapp.net",
    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:

```ts
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:

```ts
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.