# A Brief Guide of SendMammy API

### Introduction

#### Scope

This document aims to describe and provide guidelines in integrating our client's systems to the Send Mammy Service.

#### Audience

This document is intended for:

* ChatDaddy Developers; enabling them to quickly learn to integrate and continuously improve the service
* External third-party developers / organizations; enabling them to use and incorporate service into their own systems

### Glossary

| Terms     | Descriptions                                                       |
| --------- | ------------------------------------------------------------------ |
| ChatDaddy | The company maintaining and managing the service                   |
| WhatsApp  | A simple, secure and reliable messaging platform                   |
| Swagger   | The toolset for API Documentation                                  |
| Service   | The Send Mammy Service                                             |
| JWT       | Json Web Tokens                                                    |
| jid       | The user WhatsApp ID and it comes with a format of @s.whatsapp.net |

### Overview

**Send Mammy** is the most advanced, feature-rich unofficial API for [**WhatsApp**](https://www.whatsapp.com/) and developed by [**ChatDaddy**](https://chatdaddy.tech/). The Service follows the industry-standard protocol for authorization by using [**OAuth 2.0**](https://oauth.net/2/) and using [JWT](https://jwt.io/introduction) for the tokens.

The endpoints are officially documented using [Swagger](https://api-wa.chatdaddy.tech/docs/) and following the [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0)

### How to Integrate

* **Get a Token**

  A user can get a token by consuming an authentication endpoint from our OAuth service. Before a user can get an access token you must have your **username** and **password** registered from the service

**Sample Request**

```
curl -X 'POST' \\
  '<https://api-auth.chatdaddy.tech/oauth2/token>' \\
  -H 'accept: application/json' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "username": "string:<your username here>",
  "password": "string:<your password here>",
  "grant_type": "password"
}'
```

**Sample Success Response**

```
{
  "access_token": "string:<access token>",
  "access_token_expiration": number:<access token expiration>,
  "refresh_token": "string:<refresh token>",
  "refresh_token_expiration": number:<refresh token expiration>,
  "tokenType": "Bearer"
}
```

**Sample Error Response**

```
{
  "status": "error",
  "message": "string:<error message description>",
  "code": number:<status code>
}
```

* **Get WhatsApp Web Connection State**

  A user can get the current state of the WhatsApp web connection by consuming the the `GET /` of the service

**Sample Request**

```
curl -X 'GET' \\
  '<https://api.sendmammy.com/>' \\
  -H 'accept: application/json' \\
  -H 'Authorization: Bearer <access token here>'
```

**Sample Success Response**

```
{
  "connections": {
    "phone": false,
    "waWeb": "string:<state of whatsapp web connection>(open|close|connecting)"
  },
  "chats": {
    "hasSome": boolean:<has some chats>,
    "hasLatest": boolean:<has latest chats>
  },
  "canLogin": boolean:<is the user can login to whatsapp web>,
  "user": {
    "jid": "string:<jid>",
    "name": "string:<name of the user>",
    "phone": {
      "wa_version": "string:<whatsapp version",
      "mcc": "string:<mcc>",
      "mnc": "string:<mnc>",
      "os_version": "string:<os version>",
      "device_manufacturer": "string:<device manufacturer>",
      "device_model": "string:<device model>",
      "os_build_number": "string:<os build number>"
    },
    "imgUrl": "string:<profile picture url>"
  },
  "pendingQR": "string:<WhatsApp QR Code Data>",
  "mediaUploadsUrl": "string:<media upload url>",
  "messagesLeft": {
    "count": number:<message limit count>,
    "unlimited": boolean:<is the user's messages is unlimited>
  }
}
```

* **Open WhatsApp Web Connection**

  A user needs to open a WhatsApp Web connection to maximize the use of the Send Mammy service. If the user received a `canLogin=true` from the `Get WhatsApp Web Connection State` it will successfully logged in the WhatsApp account to the service. Otherwise, the `pendingQR` will be seen on `Get WhatsApp Web Connection State` response. `pendingQR` is a QR code data that must be used within `20 seconds` to generate a QR code for WhatsApp to scan. Once this QR code is successfully scanned from WhatsApp, the user will now be logged in to the service.

**Sample Request**

```
curl -X 'POST' \\
  '<https://api.sendmammy.com/open>' \\
  -H 'accept: application/json' \\
  -H 'Authorization: Bearer <access token here>' \\
  -d ''
```

If the response code returned by the request is `200` , this means that the opening a WhatsApp Web connections is successfully registered.

* **Sending a Message**

  After successfully connected the user's WhatsApp account to the service, The user can now send message to it's recipients.

**Sample Request (Text Message)**

```
curl -X 'POST' \\
  '<https://api.sendmammy.com/messages/><user jid here>' \\
  -H 'accept: application/json' \\
  -H 'Authorization: Bearer <access token here>' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "jid": "<recipient jid here>",
  "text": "This is a test message",
  "scheduleAt": <can be current unix time or desired schedule of the message to be sent out>,
  "randomizeMessage": true
}'
```

**Sample Response (Text Message)**

```
{
  "key": {
    "remoteJid": "string:<sender jid>",
    "fromMe": boolean:<is from the sender>,
    "id": "string:<message ID>"
  },
  "message": {
    "extendedTextMessage": {
      "text": "This is a test message"
    }
  },
  "messageTimestamp": {
    "low": 1618311227,
    "high": 0,
    "unsigned": true
  },
  "status": 1,
  "scheduled": true,
  "senderUserId": "string:<sender user id>"
}
```

**Sample Request (Media Message)**

```
curl -X 'POST' \\
  '<https://api.sendmammy.com/messages/><user jid here>' \\
  -H 'accept: application/json' \\
  -H 'Authorization: Bearer <access token here>' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "jid": "<recipient jid here>",
  "image": {
    "url": "<image url>",
    "mimetype": "<image mime type>",
    "name": "<image name>"
  },
  "scheduleAt": 1618312071,
  "withTyping": true,
  "randomizeMessage": true
}'
```

**Sample Response (Media Message)**

```
{
  "key": {
    "remoteJid": "string:<sender jid>",
    "fromMe": boolean:<is from the sender>,
    "id": "string:<message ID>"
  },
  "message": {
    "imageMessage": {
      "url": "string:<.enc image url>",
      "mimetype": "img/jpg",
      "fileSha256": {
        "type": "Buffer",
        "data": [<buffer data>]
      },
      "fileLength": {
        "low": 187360,
        "high": 0,
        "unsigned": true
      },
      "mediaKey": {
        "type": "Buffer",
        "data": [<buffer data>]
      },
      "fileEncSha256": {
        "type": "Buffer",
        "data": [<buffer data>]
      }
    }
  },
  "messageTimestamp": {
    "low": 1618312071,
    "high": 0,
    "unsigned": true
  },
  "status": 1,
  "scheduled": true,
  "withTyping": true,
  "senderUserId": "string:<sender user id>"
}
```

**Sample Request (Contact)**

```
curl -X 'POST' \\
  '<https://api.sendmammy.com/messages/><user jid here>' \\
  -H 'accept: application/json' \\
  -H 'Authorization: Bearer <access token here>' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "jid": "<recipient jid here>",
  "contacts": [
	{
	    "displayName": "<Contact Name>",
	    "phoneNumber": "<Contact Phone Number>"
	}
  ],
  "scheduleAt": 1618312684,
  "withTyping": true,
  "randomizeMessage": false
}'
```

**Sample Response (Contact)**

```
{
  "key": {
    "remoteJid": "string:<sender jid>",
    "fromMe": boolean:<is from the sender>,
    "id": "string:<message ID>"
  },
  "message": {},
  "messageTimestamp": {
    "low": 1618312684,
    "high": 0,
    "unsigned": true
  },
  "status": 1,
  "scheduled": true,
  "withTyping": true,
  "senderUserId": "string:<sender user id>"
}
```

**Sample Request (Location)**

```
curl -X 'POST' \\
  '<https://api.sendmammy.com/messages/><user jid here>' \\
  -H 'accept: application/json' \\
  -H 'Authorization: Bearer <access token here>' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "jid": "<recipient jid here>",
  "location": {
    "degreesLongitude": 53.2734,
    "degreesLatitude": -7.77832031
  },
  "scheduleAt": 1618311554,
  "withTyping": true,
  "randomizeMessage": true
}'
```

**Sample Response (Location)**

```
{
  "key": {
    "remoteJid": "string:<sender jid>",
    "fromMe": boolean:<is from the sender>,
    "id": "string:<message ID>"
  },
  "message": {
    "locationMessage": {
      "degreesLatitude": -7.77832031,
      "degreesLongitude": 53.2734
    }
  },
  "messageTimestamp": {
    "low": 1618311554,
    "high": 0,
    "unsigned": true
  },
  "status": 1,
  "scheduled": true,
  "withTyping": true,
  "senderUserId": "string:<sender user id>"
}
```

### Are you excited to do an Advance Integration?

We are excited to hear that from you! You can explore more about the service by using our official [API documentation](https://api-wa.chatdaddy.tech/docs/).

**Basic Guide to Continuosly Explore**

![https://s3-us-west-2.amazonaws.com/secure.notion-static.com/a627957f-40bc-4a39-ac16-1593c11e999d/Untitled.png](https://s3-us-west-2.amazonaws.com/secure.notion-static.com/a627957f-40bc-4a39-ac16-1593c11e999d/Untitled.png)

* The **Server** selected must be `https://api.sendmammy.com/`
* To prevent getting `Unauthorized Request`, kindly ensure that you have clicked the `Authorize` button on the right
* Upon clicking the `Authorize` button, the documentation will prompt an authorization modal like the image below:

![https://s3-us-west-2.amazonaws.com/secure.notion-static.com/f23dfe95-822f-4114-9d95-33142ba95971/Untitled.png](https://s3-us-west-2.amazonaws.com/secure.notion-static.com/f23dfe95-822f-4114-9d95-33142ba95971/Untitled.png)

* The user must fill up a valid `username` and `password` and just click the `Authorize` button on the bottom part of the modal.
* `client_id` & `client_secret` can be blank
* The user can verify a successful authorization request by seeing if the lock icon is `locked`

![https://s3-us-west-2.amazonaws.com/secure.notion-static.com/38fd696e-8a13-4514-9e8f-c11bbac44479/Untitled.png](https://s3-us-west-2.amazonaws.com/secure.notion-static.com/38fd696e-8a13-4514-9e8f-c11bbac44479/Untitled.png)

* The user can now request to all the endpoints of the service
* NOTE: Don't forget to read the descriptions on the `endpoint`, `parameters`, `request objects`, and `response objects` for better understanding. If you have any concerns, please don't hesitate to contact our sales representative or support team.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.chatdaddy.tech/chatdaddy-api/a-brief-guide-of-sendmammy-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.