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

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

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

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.

PreviousWhatsApp API NextListing Message Templates

Last updated 1 year ago