Skip to content

Commit

Permalink
DX-1816 java readme update (#29)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jmulford-bw
jmulford-bw authored Apr 29, 2021
1 parent a9371a0 commit f8ea468
Show file tree
Hide file tree
Showing 2 changed files with 139 additions and 61 deletions.
173 changes: 112 additions & 61 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,101 +1,152 @@
# Bandwidth Java SDK

Bandwidth's API docs can be found at https://dev.bandwidth.com

Java specific docs can be found at https://dev.bandwidth.com/sdks/java.html
## Getting Started

## Download & Install
### Installation

Maven:
Add the following dependency to your `pom.xml` file

```xml
```
<!-- https://mvnrepository.com/artifact/com.bandwidth.sdk/bandwidth-sdk -->
<dependency>
<groupId>com.bandwidth.sdk</groupId>
<artifactId>bandwidth-sdk</artifactId>
<version>1.0.0</version>
<version>{version}</version>
</dependency>
```

## Initialize Bandwidth Client

```java
### Initialize

//Set the voice client configuration with credentials
```
BandwidthClient client = new BandwidthClient.Builder()
.messagingBasicAuthCredentials("MESSAGING_API_TOKEN", "MESSAGING_API_SECRET")
.voiceBasicAuthCredentials("VOICE_API_USERNAME", "VOICE_API_PASSWORD")
.environment(Environment.PRODUCTION)
.messagingBasicAuthCredentials("username", "password")
.voiceBasicAuthCredentials("username", "password")
.twoFactorAuthBasicAuthCredentials("username", "password")
.webRtcBasicAuthCredentials("username", "password")
.build();
String accountId = "12345";
```

### Create A Phone Call

//Fully qualified name to remove confilicts
com.bandwidth.messaging.controllers.APIController messagingController = client.getMessagingClient().getAPIController();
```
com.bandwidth.voice.controllers.APIController voiceController = client.getVoiceClient().getAPIController();
String to = "+15554443333";
String from = "+15553334444";
String applicationId = "3-a-b-c";
String answerUrl = "https://sample.com";
ApiCreateCallRequest body = new ApiCreateCallRequest();
body.setTo(to);
body.setFrom(from);
body.setApplicationId(applicationId);
body.setAnswerUrl(answerUrl);
ApiResponse<ApiCallResponse> createCallResponse = voiceController.createCall(accountId, body);
System.out.println(createCallResponse.getResult().getCallId());
```

## Create Phone Call
### Send A Text Message

```java
import com.bandwidth.voice.models.ApiCreateCallRequest;
```
String to = "+15554443333";
ArrayList<String> toNumbers = new ArrayList<String>();
toNumbers.add(to);
String from = "+15553334444";
String applicationId = "3-a-b-d";
String text = "Hello from Java";
MessageRequest body = new MessageRequest();
body.setTo(toNumbers);
body.setFrom(from);
body.setText(text);
body.setApplicationId(applicationId);
ApiResponse<BandwidthMessage> createMessageResponse = messagingController.createMessage(accountId, body);
System.out.println(createMessageResponse.getResult().getMessageId());
```

//Create the ApiCreateCallRequst object and populate.
ApiCreateCallRequest callRequest = new ApiCreateCallRequest();
### Create BXML

callRequest.setApplicationId("application.Id");
callRequest.setTo("+19999999999");
callRequest.setAnswerUrl("https://test.com");
callRequest.setFrom("+17777777777");
```
SpeakSentence speakSentence = SpeakSentence.builder()
.text("Hello world")
.voice("susan")
.gender("female")
.locale("en_US")
.build();
String response = new Response()
.add(speakSentence)
.toBXML();
System.out.println(response);
```

//The voice client createCall can throw these exceptions.
try {
ApiResponse<ApiCallResponse> response = voiceController.createCall("account.id", callRequest);
System.out.println(response.getResult().getCallId());
} catch (IOException | ApiException e) {
//Handle
}
### Create A MFA Request

```
String to = "+15554443333";
String from = "+15553334444";
String applicationId = "3-a-c-b");
String scope = "scope";
int digits = 6;
String message = "Your temporary {NAME} {SCOPE} code is {CODE}";
TwoFactorCodeRequestSchema body = new TwoFactorCodeRequestSchema();
body.setTo(to);
body.setFrom(from);
body.setApplicationId(applicationId);
body.setScope(scope);
body.setDigits(digits);
body.setMessage(message);
mfaController.createVoiceTwoFactor(accountId, body);
String code = "123456"; //this is the user code to verify
int expirationTimeInMinutes = 3;
TwoFactorVerifyRequestSchema body = new TwoFactorVerifyRequestSchema();
body.setTo(to);
body.setApplicationId(applicationId);
body.setScope(scope);
body.setCode(code);
body.setExpirationTimeInMinutes(expirationTimeInMinutes);
ApiResponse<TwoFactorVerifyCodeResponse> response = mfaController.createVerifyTwoFactor(accountId, body);
System.out.println(response.getResult().getValid());
```

## Generate BXML
### WebRtc Participant & Session Management

```java
import com.bandwidth.sdk.voice.models.verbs.*;
```
Session createSessionBody = new Session();
createSessionBody.setTag("new-session");
//Create a Bandwidth XML (BXML) SpeakSentence Verb. Supply the sentence to be spoken.
SpeakSentence speakSentence = SpeakSentence.builder()
.text("Hello World")
.build();
ApiResponse<Session> createSessionResponse = webrtcController.createSession(accountId, createSessionBody);
String sessionId = createSessionResponse.getResult().getId();
//Create the response object and add the speakSentence verb to the response.
Response response = Response.builder().build().add(speakSentence);
Participant createParticipantBody = new Participant();
createParticipantBody.setCallbackUrl("https://sample.com");
ArrayList<PublishPermissionEnum> publishPermissions = new ArrayList<PublishPermissionEnum>();
publishPermissions.add(PublishPermissionEnum.AUDIO);
publishPermissions.add(PublishPermissionEnum.VIDEO);
//view the BXML
System.out.println( response.toXml() )
ApiResponse<AccountsParticipantsResponse> createParticipantResponse = webrtcController.createParticipant(accountId, createParticipantBody);
String participantId = createParticipantResponse.getResult().getParticipant().getId();
webrtcController.addParticipantToSession(accountId, sessionId, participantId, null);
```

## Send Text Message
## Supported Java Versions

```java
import com.bandwidth.messaging.models.MessageRequest;
This package can be used with Java >= 1.8

MessageRequest messageRequest = new MessageRequest();
## Documentation

List<String> toNumbers = new ArrayList<>();
Documentation for this package can be found at https://dev.bandwidth.com/sdks/java.html

toNumbers.add("+12345678902");
## Credentials

messageRequest.setApplicationId(MSG_APPLICATION_ID);
messageRequest.setText("Hey, check this out!");
messageRequest.setFrom("+12345678901");
messageRequest.setTo( toNumbers );
messageRequest.setTag("test tag");
Information for credentials for this package can be found at https://dev.bandwidth.com/guides/accountCredentials.html

try {
ApiResponse<BandwidthMessage> response = messagingController.createMessage(accountId, messageRequest);
System.out.println(response.getResult().getId());
} catch (ApiException | IOException e){
//Handle
}
```
27 changes: 27 additions & 0 deletions src/test/java/com/bandwidth/ApiTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@
import com.bandwidth.twofactorauth.models.*;
import com.bandwidth.twofactorauth.controllers.*;
import com.bandwidth.twofactorauth.exceptions.*;
import com.bandwidth.webrtc.models.*;
import com.bandwidth.webrtc.controllers.*;
import com.bandwidth.exceptions.ApiException;
import com.bandwidth.http.response.ApiResponse;
import com.bandwidth.utilities.FileWrapper;
Expand All @@ -37,17 +39,20 @@ public class ApiTest {
private com.bandwidth.messaging.controllers.APIController messagingController;
private com.bandwidth.voice.controllers.APIController voiceController;
private com.bandwidth.twofactorauth.controllers.MFAController mfaController;
private com.bandwidth.webrtc.controllers.APIController webrtcController;

@Before
public void init() {
this.client = new BandwidthClient.Builder()
.messagingBasicAuthCredentials(System.getenv("BW_USERNAME"), System.getenv("BW_PASSWORD"))
.voiceBasicAuthCredentials(System.getenv("BW_USERNAME"), System.getenv("BW_PASSWORD"))
.twoFactorAuthBasicAuthCredentials(System.getenv("BW_USERNAME"), System.getenv("BW_PASSWORD"))
.webRtcBasicAuthCredentials(System.getenv("BW_USERNAME"), System.getenv("BW_PASSWORD"))
.build();
this.messagingController = client.getMessagingClient().getAPIController();
this.voiceController = client.getVoiceClient().getAPIController();
this.mfaController = client.getTwoFactorAuthClient().getMFAController();
this.webrtcController = client.getWebRtcClient().getAPIController();
}

@Test
Expand Down Expand Up @@ -282,6 +287,28 @@ public void testMfaVerifyInvalidPhoneNumber() throws Exception {
mfaController.createVerifyTwoFactor(accountId, body);
}

@Test
public void testWebRtcParticipantSessionManagement() throws Exception {
String accountId = System.getenv("BW_ACCOUNT_ID");

Session createSessionBody = new Session();
createSessionBody.setTag("new-session");

ApiResponse<Session> createSessionResponse = webrtcController.createSession(accountId, createSessionBody);
String sessionId = createSessionResponse.getResult().getId();

Participant createParticipantBody = new Participant();
createParticipantBody.setCallbackUrl("https://sample.com");
ArrayList<PublishPermissionEnum> publishPermissions = new ArrayList<PublishPermissionEnum>();
publishPermissions.add(PublishPermissionEnum.AUDIO);
publishPermissions.add(PublishPermissionEnum.VIDEO);

ApiResponse<AccountsParticipantsResponse> createParticipantResponse = webrtcController.createParticipant(accountId, createParticipantBody);
String participantId = createParticipantResponse.getResult().getParticipant().getId();

webrtcController.addParticipantToSession(accountId, sessionId, participantId, null);
}

/*
* Taken from https://mkyong.com/java/how-to-convert-inputstream-to-string-in-java/
*/
Expand Down

0 comments on commit f8ea468

Please sign in to comment.