English | 中文
Whatsapp business api SDK, written in java. This SDK implements the Official Whatsapp Cloud API and WhatsApp Business Management API and Engagelab Whatsapp API. These allows you to:
The WhatsApp Business API allows medium and large businesses to communicate with their customers at scale. Using the API, businesses can build systems that connect thousands of customers with agents or bots, enabling both programmatic and manual communication. Additionally, you can integrate the API with numerous backend systems, such as CRM and marketing platforms.
This sdk implements whatsapp business cloud api version v16.0. See api changelog
This sdk implements engagelab whatsapp API version v1.
:warning: This project is still under construction. Contributions are welcome.
See javadoc
:warning: this library is compatible with java 1.8+.
1. Add the JitPack repository to your build file:
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
2. Add the following Maven dependency to your project's pom.xml
:
<dependency>
<groupId>com.github.harmonyzhang</groupId>
<artifactId>whatsapp-business-java-sdk</artifactId>
<version>v1.0.1</version>
</dependency>
1. Add it in your root build.gradle at the end of repositories:
allprojects {
repositories {
...
maven { url 'https://jitpack.io' }
}
}
2. Add the dependency
dependencies {
implementation 'com.github.harmonyzhang:whatsapp-business-java-sdk:v1.0.1'
}
3. Install library into your Maven's local repository by running mvn install
Alternatively, you can clone this repository and run the examples.
There are two client classes that can be used to interact with the API:
WhatsappBusinessCloudApi
, a synchronous/blocking WhatsApp Business Platform Cloud API client;
Send and receive messages using a cloud-hosted version of the WhatsApp Business Platform. The Cloud API allows you to implement WhatsApp Business APIs without the cost of hosting of your own servers and also allows you to more easily scale your business messaging.
WhatsappApiFactory factory = WhatsappApiFactory.newInstance();
WhatsappBusinessCloudApi whatsappBusinessCloudApi = factory.newBusinessCloudApi(TestConstants.TOKEN);
WhatsappBusinessManagementApi
, a synchronous/blocking WhatsApp Business Management API client;
The WhatsApp Business Management API allows you to programmatically manage your WhatsApp Business Account assets, such as message templates and phone numbers.
WhatsappApiFactory factory = WhatsappApiFactory.newInstance();
WhatsappBusinessManagementApi whatsappBusinessCloudApi = factory.newBusinessManagementApi(TestConstants.TOKEN);
WhatsappEngagelabApi
, a synchronous/blocking Engagelab Whatsapp API client;
需要有个极光账号并开通whatsapp服务.
WhatsappApiFactory factory = WhatsappApiFactory.newInstance();
WhatsappEngagelabApi whatsappEngagelabApi = factory.newEngagelabApi(TestConstants.ENGAGELAB_DEV_KEY,TestConstants.ENGAGELAB_DEV_SECRET);
These can be instantiated through the corresponding factory method of WhatsappApiFactory
, by passing the token, which can be created following the instructions at whatsapp.
WhatsappApiFactory factory = WhatsappApiFactory.newInstance();
WhatsappBusinessCloudApi whatsappBusinessCloudApi = factory.newBusinessCloudApi(TestConstants.TOKEN);
Message message = MessageBuilder.builder()//
.setTo(TestConstants.PHONE_NUMBER_1)//
.buildTextMessage(new TextMessage()//
.setBody(Formatter.bold("Hello world!") + "\nSome code here: \n" + Formatter.code("hello world code here"))//
.setPreviewUrl(false));
whatsappBusinessCloudApi.sendMessage(TestConstants.PHONE_NUMBER_ID, message);
Result:
WhatsappApiFactory factory = WhatsappApiFactory.newInstance();
WhatsappBusinessCloudApi whatsappBusinessCloudApi = factory.newBusinessCloudApi(TestConstants.TOKEN);
Message message = MessageBuilder.builder()//
.setTo(TestConstants.PHONE_NUMBER_1)//
.buildTemplateMessage(//
new TemplateMessage()//
.setLanguage(new Language(LanguageType.PT_BR))//
.setName("schedule_confirmation3")//
.addComponent(//
new Component(ComponentType.BODY)//
.addParameter(new TextParameter("Mauricio"))//
.addParameter(new TextParameter("04/11/2022"))//
.addParameter(new TextParameter("14:30")))//
);
whatsappBusinessCloudApi.sendMessage(TestConstants.PHONE_NUMBER_ID, message);
Result:
WhatsappApiFactory factory = WhatsappApiFactory.newInstance();
WhatsappBusinessCloudApi whatsappBusinessCloudApi = factory.newBusinessCloudApi(TestConstants.TOKEN);
Message message = MessageBuilder.builder()//
.setTo(TestConstants.PHONE_NUMBER_1)//
.buildContactMessage(new ContactMessage()//
.addContacts(new ContactsItem()//
.addPhones(new PhonesItem()//
.setPhone(TestConstants.PHONE_NUMBER_1)//
.setType(AddressType.HOME))//
.setName(new Name()//
.setFormattedName("Mauricio Binda")//
.setFirstName("Mauricio"))//
));
whatsappBusinessCloudApi.sendMessage(TestConstants.PHONE_NUMBER_ID, message);
Result:
WhatsappApiFactory factory = WhatsappApiFactory.newInstance();
WhatsappBusinessCloudApi whatsappBusinessCloudApi = factory.newBusinessCloudApi(TestConstants.TOKEN);
Message message = MessageBuilder.builder()//
.setTo(TestConstants.PHONE_NUMBER_1)//
.buildInteractiveMessage(InteractiveMessage.build() //
.setAction(new Action() //
.addButton(new Button() //
.setType(ButtonType.REPLY)
.setReply(new Reply() //
.setId("UNIQUE_BUTTON_ID_1") //
.setTitle("BUTTON_TITLE_1"))) //
.addButton(new Button() //
.setType(ButtonType.REPLY)
.setReply(new Reply() //
.setId("UNIQUE_BUTTON_ID_2") //
.setTitle("BUTTON_TITLE_2")))
) //
.setType(InteractiveMessageType.BUTTON) //
.setBody(new Body() //
.setText("Body message")) //
);
MessageResponse messageResponse = whatsappBusinessCloudApi.sendMessage(TestConstants.PHONE_NUMBER_ID, message);
System.out.println(messageResponse);
Result:
WhatsappApiFactory factory = WhatsappApiFactory.newInstance();
WhatsappBusinessCloudApi whatsappBusinessCloudApi = factory.newBusinessCloudApi(TestConstants.TOKEN);
Message message = MessageBuilder.builder()//
.setTo(TestConstants.PHONE_NUMBER_1)//
.buildInteractiveMessage(InteractiveMessage.build() //
.setAction(new Action() //
.setButtonText("BUTTON_TEXT") //
.addSection(new Section() //
.setTitle("Title 1") //
.addRow(new Row() //
.setId("SECTION_1_ROW_1_ID") //
.setTitle("Title 1") //
.setDescription("SECTION_1_ROW_1_DESCRIPTION")) //
.addRow(new Row() //
.setId("SECTION_1_ROW_2_ID") //
.setTitle("Title 2") //
.setDescription("SECTION_1_ROW_2_DESCRIPTION")) //
.addRow(new Row() //
.setId("SECTION_1_ROW_3_ID") //
.setTitle("Title 3") //
.setDescription("SECTION_1_ROW_3_DESCRIPTION")) //
) //
.addSection(new Section() //
.setTitle("Title 2") //
.addRow(new Row() //
.setId("SECTION_2_ROW_1_ID") //
.setTitle("Title 1") //
.setDescription("SECTION_2_ROW_1_DESCRIPTION")) //
.addRow(new Row() //
.setId("SECTION_2_ROW_2_ID") //
.setTitle("Title 2") //
.setDescription("SECTION_2_ROW_2_DESCRIPTION")) //
.addRow(new Row() //
.setId("SECTION_2_ROW_3_ID") //
.setTitle("Title 3") //
.setDescription("SECTION_2_ROW_3_DESCRIPTION")) //
)
) //
.setType(InteractiveMessageType.LIST) //
.setHeader(new Header() //
.setType(HeaderType.TEXT) //
.setText("Header Text")) //
.setBody(new Body() //
.setText("Body message")) //
.setFooter(new Footer() //
.setText("Footer Text")) //
);
MessageResponse messageResponse = whatsappBusinessCloudApi.sendMessage(TestConstants.PHONE_NUMBER_ID, message);
System.out.println(messageResponse);
Result:
WhatsappApiFactory factory = WhatsappApiFactory.newInstance();
WhatsappBusinessCloudApi whatsappBusinessCloudApi = factory.newBusinessCloudApi(TestConstants.TOKEN);
var audioMessage = new AudioMessage()//
.setId("6418001414900549");
Message message = MessageBuilder.builder()//
.setTo(TestConstants.PHONE_NUMBER_1)//
.buildAudioMessage(audioMessage);
MessageResponse messageResponse = whatsappBusinessCloudApi.sendMessage(TestConstants.PHONE_NUMBER_ID, message);
Result:
WhatsappApiFactory factory = WhatsappApiFactory.newInstance();
WhatsappBusinessCloudApi whatsappBusinessCloudApi = factory.newBusinessCloudApi(TestConstants.TOKEN);
var documentMessage = new DocumentMessage()//
.setId("1238834210396519")// media id (uploaded before)
.setCaption("Media Object details from developers.facebook.com")//
.setFileName("Media oject.pdf");
Message message = MessageBuilder.builder()//
.setTo(TestConstants.PHONE_NUMBER_1)//
.buildDocumentMessage(documentMessage);
MessageResponse messageResponse = whatsappBusinessCloudApi.sendMessage(TestConstants.PHONE_NUMBER_ID, message);
Result:
WhatsappApiFactory factory = WhatsappApiFactory.newInstance();
WhatsappBusinessCloudApi whatsappBusinessCloudApi = factory.newBusinessCloudApi(TestConstants.TOKEN);
var imageMessage = new ImageMessage()//
.setLink("https://upload.wikimedia.org/wikipedia/pt/4/45/Yoda.jpg").setCaption("See this image, please");
Message message = MessageBuilder.builder()//
.setTo(TestConstants.PHONE_NUMBER_1)//
.buildImageMessage(imageMessage);
MessageResponse messageResponse = whatsappBusinessCloudApi.sendMessage(TestConstants.PHONE_NUMBER_ID, message);
WhatsappApiFactory factory = WhatsappApiFactory.newInstance();
WhatsappBusinessCloudApi whatsappBusinessCloudApi = factory.newBusinessCloudApi(TestConstants.TOKEN);
var imageMessage = new ImageMessage()//
.setId("186057067456357")// media id (uploaded before)
.setCaption("See this image, please");
Message message = MessageBuilder.builder()//
.setTo(TestConstants.PHONE_NUMBER_1)//
.buildImageMessage(imageMessage);
MessageResponse messageResponse = whatsappBusinessCloudApi.sendMessage(TestConstants.PHONE_NUMBER_ID, message);
Result:
WhatsappApiFactory factory = WhatsappApiFactory.newInstance();
WhatsappBusinessCloudApi whatsappBusinessCloudApi = factory.newBusinessCloudApi(TestConstants.TOKEN);
var stickerMessage = new StickerMessage()//
.setId("527984052814860");// media id (uploaded before)
Message message = MessageBuilder.builder()//
.setTo(TestConstants.PHONE_NUMBER_1)//
.buildStickerMessage(stickerMessage);
MessageResponse messageResponse = whatsappBusinessCloudApi.sendMessage(TestConstants.PHONE_NUMBER_ID, message);
Result:
WhatsappApiFactory factory = WhatsappApiFactory.newInstance();
WhatsappBusinessCloudApi whatsappBusinessCloudApi = factory.newBusinessCloudApi(TestConstants.TOKEN);
var videoMessage = new VideoMessage()//
.setId("1236364143659727")// media id (uploaded before)
.setCaption("See this video");
Message message = MessageBuilder.builder()//
.setTo(TestConstants.PHONE_NUMBER_1)//
.buildVideoMessage(videoMessage);
MessageResponse messageResponse = whatsappBusinessCloudApi.sendMessage(TestConstants.PHONE_NUMBER_ID, message);
WhatsappApiFactory factory = WhatsappApiFactory.newInstance();
WhatsappBusinessManagementApi whatsappBusinessCloudApi = factory.newBusinessManagementApi(TestConstants.TOKEN);
var template = new MessageTemplate();
template.setName("schedule_confirmation3")//
.setCategory(Category.TRANSACTIONAL)//
.setLanguage(Language.PT_BR)//
.addComponent(new HeaderComponent()//
.setText("Confirmação de Atendimento")//
.setFormat(HeaderFormat.TEXT))//
.addComponent(new BodyComponent()//
.setText("Olá " + Formatter.bold("{{1}}") + ", passando aqui para confirmar seu horário no dia " + Formatter.bold("{{2}}") + " as " + Formatter.bold("{{3}}h") + ".\nVocê confirma que comparecerá?")//
.setExample(new Example()//
.addBodyTextExamples("Maria", "04/11/2022", "13:30")//
))//
.addComponent(new ButtonComponent()//
.addButton(new QuickReplyButton("SIM"))//
.addButton(new QuickReplyButton("NÃO"))//
.addButton(new QuickReplyButton("REMARCAR")//
)
)//
.addComponent(new FooterComponent().setText("Utilize um dos botões abaixo para a confirmação"))
;
var response = whatsappBusinessCloudApi.createMessageTemplate(TestConstants.WABA_ID, template);
Webhooks are triggered when a customer performs an action or the status for a message a business sends a customer changes.
WebHook objects are mapped on WebHookEvent class
See Whatsapp api documentation for more details. Example:
//payload = the webhook payload json sent by Whatsapp
//using WebHook.constructEvent() to deserialize event
WebHookEvent event = WebHook.constructEvent(payload);
See an example here
You get a webhooks notification:
1- When a customer performs an action
2- When the status for a message received by a business changes (includes pricing information)
3- When WhatsApp Business Management API updates:
You can use 4 different endpoints to manage your media:
See the examples:
WhatsappApiFactory factory = WhatsappApiFactory.newInstance();
WhatsappBusinessCloudApi whatsappBusinessCloudApi = factory.newBusinessCloudApi(TestConstants.TOKEN);
var fileName = "starwars.png";
byte[] fileContent = Files.readAllBytes(Paths.get("src/test/resources/" + fileName));
var response = whatsappBusinessCloudApi.uploadMedia(TestConstants.PHONE_NUMBER_ID, fileName, FileType.PNG, fileContent);
System.out.println(response);
WhatsappApiFactory factory = WhatsappApiFactory.newInstance();
WhatsappBusinessCloudApi whatsappBusinessCloudApi = factory.newBusinessCloudApi(TestConstants.TOKEN);
var response = whatsappBusinessCloudApi.retrieveMediaUrl("1227829768162607");
System.out.println(response);
WhatsappApiFactory factory = WhatsappApiFactory.newInstance();
WhatsappBusinessCloudApi whatsappBusinessCloudApi = factory.newBusinessCloudApi(TestConstants.TOKEN);
//delete media
var response = whatsappBusinessCloudApi.deleteMedia("723050006231302");
System.out.println(response);
WhatsappApiFactory factory = WhatsappApiFactory.newInstance();
WhatsappBusinessCloudApi whatsappBusinessCloudApi = factory.newBusinessCloudApi(TestConstants.TOKEN);
// retrieve the media file url
var mediaUrl = whatsappBusinessCloudApi.retrieveMediaUrl("723050006231302");
//call downloadMediaFile() -> return a MediaFile object with the file name and content (byte[])
var mediaFile = whatsappBusinessCloudApi.downloadMediaFile(mediaUrl.url());
//write the file in the folder "/examples/"
Files.write(Path.of("src/test/java/com/whatsapp/api/examples/" + mediaFile.fileName()), mediaFile.content());