WhatsApp Groups API

This documentation provides the information you need for integration with the Wavy Messaging platform for managing groups through the Wavy WhatsApp Integration. The API has REST integration, using the HTTP protocol with TLS, supporting the POST method with parameters sent in JSON format.

Authentication

In order to successfully use our API, you are required to present a valid user name - or email - and the associated authentication token. While creating the request, you have to provide the following parameters on the headers:

Field	Details	Data Type
userName	Name or email valid for authentication on Wavy Messaging.	String
authenticationToken	Authentication token generated by our platform. Find it here or consult the support. here​	String

Connection Details

​	​
Hostname	api-messaging.wavy.global
Port	443 (https)
Protocol	HTTPS (TLS encryption)
Authentication	username + token
Encoding	UTF-8

Sending Messages to Groups

When sending messages to groups, the request is similar to that of direct messages. Only the Destination object needs to be adapted.

POST https://api-messaging.wavy.global/v1/whatsapp/send

The request body must contain the same fields as in Sending Text Messages.

Group delivery example

{
 "destinations": [{
 "destination": "5519900000000-1513616971",
 "recipientType": "group"
 }],
 "message": {
 "messageText": "Test message"
 }
 }

Group MO

Group MOs contain the same fields as Regular MOs with the addition of waGroupId indicating to which group the message was sent, as shown in the example.

Be careful if you are replying automatically to direct messages sent to your WhatsApp account. If the waGroupId field is ignored, the MO can be mistaken for a direct message instead of a group message, and you will reply with a direct message. This way you run the risk of being charged for an HSM every time the user sends you a group message if the waGroupId field is not treated correctly.

Group message example:

{
 "total": 1,
 "data": [
 {
 "source": "5419900000000",
 "origin": "5419900000000",
​
 "...",
​
 "message": {
 "type": "TEXT",
 "messageText": "Hello",
 "waGroupId": "5519900000000-1553784379"
 },
​
 "..."
 }
 ]
}

Creating Groups

Create a group by providing it with a subject or title, which is the name that will appear on the chat list. In response, you will receive a group ID you will use to send messages to the group, manage the group, etc.

Unused Groups: If you have many unused groups associated with your account, you may encounter an error (due to too many groups created). You can simply clear the groups you are no longer using by leaving them.

Request

Example

{
 "subject": "group-subject"
 }

POST https://api-messaging.wavy.global/v1/whatsapp/groups

The request body must contain a JSON object with the following fields:

Field	Required	Details	Type
subject	Yes	Group subject or title, limited to 25 characters	String

Response

Response example

 {
 "groups": [{
 "creation_time": 1513616971,
 "id": "5519900000000-1513616971"
 }]
 }

The response to a request to create a group returns a group ID that you will use to send messages to the group, manage the group, etc. If you need to obtain the group ID at another time, see the Consulting All Groups section.

The following fields are returned in a successful response:

Field	Details	Type
creation_time	Time of creation	Integer
id	Group identified for the recently created group. It must be used to uniquely identify groups in later requests, where group_id is used.	String

Consulting All Groups

Retrieve all groups in which the customer is a participant.

Request

GET https://api-messaging.wavy.global/v1/whatsapp/groups

Response

Response example

 {
 "groups": [{
 "id": "5519900000000-1513616971"
 }]
 }

The response returns the group IDs for all groups in which the customer is a participant. You can obtain more information on the group, such as list of participants and the group subject, using the call described in the Consulting Group Information section.

The following fields are returned in a successful response. If there are no groups, a JSON array of empty groups is returned.

Field	Details	Type
id	List of groups the customer participates in	String

Consulting Group Information

Use this call to obtain information on the group, including participant Ids, and group subject. To obtain the group icon, see the Consulting a Group Icon section.

Request

GET https://api-messaging.wavy.global/v1/whatsapp/groups/your-group-id

Response

Response example

{
 "groups": [{
 "admins": [
 "5519900000000"
 ],
 "creation_time": 1513616971,
 "creator": "5519900000000",
 "id": "5519900000000-1513616971",
 "participants": [
 "5519900000000"
 ],
 "subject": "group-subject"
 }]
 }

The following fields are returned in a successful response:

Field	Details	Type
admins	Group administrators. Lists the IDs of the group creator and any added administrators as described in the Adding Administrators section.	String[]
creation_time	Time of group creation	Int
creator	Group creator ID	String
id	Group ID	String
participants	Group participants. It is an array with the IDs of all group participants. Initially, it will only be the group creator. Invite users to the group creating an invite link, as described in the Creating a Group Invite Link section.	String[]
subject	Group subject	String

Updating Group Information

Updating information means setting a new group subject.

Request

Example

 {
 "subject": "new-group-subject"
 }

PUT https://api-messaging.wavy.global/v1/whatsapp/groups/your-group-id

The request body must contain a JSON object with the following fields:

Field	Required	Details	Type
subject	Yes	Update the group subject to this value, limited to 25 characters	String

Response

A successful response will return a 200 OK status and null or {}. If the group is not found, the response will be 404 Not Found.

Creating a Group Invite Link

You cannot directly add participants to the group. Participants can only be invited to the group. Create a link that participants can use to join your group.

Request

GET https://api-messaging.wavy.global/v1/whatsapp/groups/your-group-id/invite

Response

Response example

{
 "groups": [{
 "link": "group-invite-link"
 }]
 }

The following fields are returned in a successful response:

Field	Details	Type
link	Group invite link	String

Once you have a link to invite participants to the group, send the link in a text message. When a user clicks the message, they will be invited to the group.

Deleting an Invite Link

Request

DELETE https://api-messaging.wavy.global/v1/whatsapp/groups/your-group-id/invite

Response

A successful response will return a 200 OK status and null or {}.

Removing Group Members

Request

Example

 {
 "waIds": [
 "5519900000000",
 "5519900000000"
 ]
 }

DELETE https://api-messaging.wavy.global/v1/whatsapp/groups/your-group-id/participants

The request body must contain a JSON object with the following fields:

Field	Required	Details	Type
waIds	Yes	Numbers of participants to be removed from the group	String[]

Response

A successful response will return a 200 OK status and null or {}. If the phone number is not found, the response will be 400 Bad Request.

Leaving a Group

Leaving a group means you will remove yourself from the list of group participants. The Group will continue to exist with the remaining participants.

Request

POST https://api-messaging.wavy.global/v1/whatsapp/groups/your-group-id/leave

Response

A successful response will return a 200 OK status and null or {}. If the phone number is not found, the response will be 400 Bad Request.

Setting a Group Icon

Request

Example

curl -X POST \
 https://api-messaging.wavy.global/v1/whatsapp/groups/your-group-id/icon \
 -H 'authenticationToken: <authenticationtoken>'
 -H 'username: <username>' \
 -H 'Content-Type: image/jpeg' \
 --data-binary @your-file-path​

POST https://api-messaging.wavy.global/v1/whatsapp/groups/your-group-id/icon Content-Type: image/jpeg or other appropriate type

binary-image-content

In order to set a group icon, you have to upload an image from its binary content. The Content-Type header must match the image’s MIME type.

Response

A successful response will return a 200 OK status and null or {}.

Consulting a Group Icon

Request

GET https://api-messaging.wavy.global/v1/whatsapp/groups/your-group-id/icon

Response

Response example

{
 "type": "URL",
 "mimeType": "image/jpeg",
 "fileName": "groupIcon.jpeg",
 "extraData": {
 "public": true,
 "Content-Type": "image/jpeg",
 "Content-Length": "2500"
 },
 "data": "https://chatclub-cdn.wavy.global/2019/03/25/ce425ffe-bc62-421f-9261-e6819a5eab43/groupIcon.jpeg"
}

A successful response will return a 200 OK and a JSON object with the following fields. If the group does not have an associated icon, the response will be 404 Not Found.

Field	Details	Type
type	Data field type	String
mimeType	File MIME type	String
fileName	File name	String
extraData	File information	String
data	File	String

Removing a Group Icon

Request

DELETE https://api-messaging.wavy.global/v1/whatsapp/groups/your-group-id/icon

Response

A successful response will return a 200 OK status and null or {}. If the group does not have an associated icon, the response will be 404 Not Found.

Adding Administrators

By default, the only administrator of a group is its creator. More administrators can be added as long as they are already group participants. To consult the participants of a group, follow the instructions in Consulting Group Information​

Request

Example

 {
 "waIds": [
 "5519900000000",
 "5519900000000"
 ]
 }

PATCH https://api-messaging.wavy.global/v1/whatsapp/groups/your-group-id/admins

The request body must contain a JSON object with the following fields:

Field	Required	Details	Type
waIds	Yes	Numbers of participants who will become administrators	String[]

Response

A successful response will return a 200 OK status and null or {}. If the phone number is not found, the response will be 400 Bad Request.

Removing Administrators

Administrators can be removed so as to become regular group participants. To consult the administrators of a group, follow the instructions in Consulting Group Information.

Request

Example

 {
 "waIds": [
 "5519900000000"
 ]
 }

DELETE https://api-messaging.wavy.global/v1/whatsapp/groups/your-group-id/admins

The request body must contain a JSON object with the following fields:

Field	Required	Details	Type
waIds	Yes	Phone numbers of the participants who will become administrators	String[]

Response

A successful response will return a 200 OK status and null or {}. If the phone number is not found, the response will be 400 Bad Request.