JarCastingZenvia CPaaS SDK for Java
This SDK for Java was created based on the Zenvia API and Zenvia CPaaS SDK for Node.js.
Table of Contents
Features
- Text message content
- File message content
- Template message content
- Subscription handling
- Logging support
Prerequisites
Obtain an API Token
You need to create an API token in the Zenvia API console.
Installation
Client
If using maven, add to your pom this SDK:
<dependency>
<groupId>com.zenvia</groupId>
<artifactId>zenvia-api-sdk-client-apache</artifactId>
<version>1.1.0</version>
</dependency>
If you are using Gradle instead, add to your build.gradle this SDK:
dependencies {
implementation group: 'com.zenvia', name: 'zenvia-api-sdk-client-apache', version: '1.1.0'
}
You can also use the one that includes Spring Boot:
<dependency>
<groupId>com.zenvia</groupId>
<artifactId>zenvia-api-sdk-client-spring</artifactId>
<version>1.1.0</version>
</dependency>
or in build.gradle:
dependencies {
implementation group: 'com.zenvia', name: 'zenvia-api-sdk-client-spring', version: '1.1.0'
}
Webhook Controller
Add to your pom this SDK for the WebhookController over Jersey framework:
<dependency>
<groupId>com.zenvia</groupId>
<artifactId>zenvia-api-sdk-webhook-jersey</artifactId>
<version>1.1.0</version>
</dependency>
or in build.gradle:
dependencies {
implementation group: 'com.zenvia', name: 'zenvia-api-sdk-webhook-jersey', version: '1.1.0'
}
or the one for the WebhookController over Spring Web MVC framework:
<dependency>
<groupId>com.zenvia</groupId>
<artifactId>zenvia-api-sdk-webhook-webmvc</artifactId>
<version>1.1.0</version>
</dependency>
or in build.gradle
dependencies {
implementation group: 'com.zenvia', name: 'zenvia-api-sdk-webhook-webmvc', version: '1.1.0'
}
Starters
For those using Spring Boot, consider ours Starters to easily configure the Zenvia SDK in your project.
Basic Usage
import com.zenvia.api.sdk.contents.*;
import com.zenvia.api.sdk.messages.Message;
import com.zenvia.api.sdk.client.Channel;
import com.zenvia.api.sdk.client.errors.ErrorResponse;
import com.zenvia.api.sdk.client.exceptions.ApiException;
import com.zenvia.api.sdk.client.exceptions.UnsuccessfulRequestException;
// When using zenvia-api-sdk-client-apache
import com.zenvia.api.sdk.client.apache.Client;
// When using zenvia-api-sdk-client-spring
import com.zenvia.api.sdk.client.spring.Client;
// Initialization with your API token (x-api-token)
Client client = new Client("YOUR_API_TOKEN");
// Choosing the channel
Channel whatsapp = client.getChannel("whatsapp");
// Creating a text content
Content content = new TextContent("some text message here");
try {
Message response = whatsapp.sendMessage("sender-identifier", "recipient-identifier", content);
// do something here
} catch(UnsuccessfulRequestException exception) {
ErrorResponse response = exception.body;
// handle error here
} catch(ApiException exception) {
// handle error here
}
Getting Started
Sending your first message
Use the sendMessage method to send text (TextContent), file (FileContent) or template (TemplateContent) messages to your contacts.
Client client = new Client("YOUR_API_TOKEN");
Channel sms = client.getChannel("sms");
TextContent content = new TextContent("some text message");
try {
Message response = sms.sendMessage("sender-identifier", "recipient-identifier", content);
} catch(UnsuccessfulRequestException exception) {
ErrorResponse response = exception.body;
}
The response will be an Message object when successful, or an ErrorResponse object will be available on the exception.
The content types can be:
| Name | Description |
|---|---|
| TextContent | Used to send text messages to your customer. |
| FileContent | Used to send file messages to your customer. |
| TemplateContent | Used to send template messages to your customer. |
The content support by channel is described below.
| Channel | TextContent | FileContent | TemplateContent |
|---|---|---|---|
| SMS | X | ||
| X | X | X | |
| X | X |
Receiving message and message status events
Use the WebhookController class to create your webhook to receive message and message status events. The default port is 8080.
If you inform the client, url, and channel fields, a subscription will be created if it does not exist for these configurations.
In the messageEventHandler field you will receive the message events and in the messageStatusEventHandler field you will receive the message status events.
Client client = new Client("YOUR_API_TOKEN");
WebhookController webhook = new WebhookController(
new ResourceConfig(), //or an instance of RequestMappingHandlerMapping when using Spring Wev MVC version
(MessageEvent messageEvent) -> {
System.out.println("Message event:" + messageEvent);
},
(MessageStatusEvent messageStatusEvent) -> {
System.out.println("Message status event:" + messageStatusEvent);
},
client,
"https://my-webhook.company.com",
ChannelType.whatsapp
);
webhook.init();
Contributing
Pull requests are always welcome!
Please see the Contributors' Guide for more information on contributing.
