# 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](https://messaging.movile.com/messaging/user/api_configuration)​ | 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 The request body must contain the same fields as in [Sending Text Messages](http://doc-messaging.movile.com/pt.html#envio-de-mensagens-de-texto). Group delivery example ``` { "destinations": [{ "destination": "5519900000000-1513616971", "recipientType": "group" }], "message": { "messageText": "Test message" } } ``` ### Group MO Group MOs contain the same fields as [Regular MOs](http://doc-messaging.movile.com/pt.html#mo-mensagens-enviadas-pelo-usu-rio-final-para-a-conta-do-whatsapp) 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 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](http://doc-messaging.movile.com/pt.html#consulta-de-todos-os-grupos). 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 #### 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](http://doc-messaging.movile.com/pt.html#consulta-a-informa-es-de-grupo). 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](http://doc-messaging.movile.com/pt.html#consulta-a-cone-de-grupo). #### Request GET #### 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](http://doc-messaging.movile.com/pt.html#adi-o-de-administradores). | 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](http://doc-messaging.movile.com/pt.html#cria-o-de-link-de-convite-de-grupo). | String\[] | | **subject** | Group subject | String | ### Updating Group Information Updating information means setting a new group subject. #### Request Example ``` { "subject": "new-group-subject" } ``` PUT 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 #### 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 #### Response A successful response will return a 200 OK status and null or {}. ### Removing Group Members #### Request Example ``` { "waIds": [ "5519900000000", "5519900000000" ] } ``` DELETE 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 #### 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: ' -H 'username: ' \ -H 'Content-Type: image/jpeg' \ --data-binary @your-file-path​ ``` POST 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 #### 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 #### 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](http://doc-messaging.movile.com/pt.html#consulta-a-informa-es-de-grupo)​ #### Request Example ``` { "waIds": [ "5519900000000", "5519900000000" ] } ``` PATCH 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](http://doc-messaging.movile.com/pt.html#consulta-a-informa-es-de-grupo). #### Request Example ``` { "waIds": [ "5519900000000" ] } ``` DELETE 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.