> For the complete documentation index, see [llms.txt](https://docs.chatdaddy.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chatdaddy.tech/chatdaddy-api/a-brief-guide-of-sendmammy-api.md).

# 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.