Zenvia 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
• Prerequisites
• Installation
• Basic Usage
• Getting Started
• Contributing
• License

Features

• Text message content
• File message content
• Template message content
• Subscription handling
• Logging support

Prerequisites

• Sign up for a Zenvia Account
• Java

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
WhatsApp	X	X	X
Facebook	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.

License

MIT