|
1 | | -# twilio-java |
| 1 | +# twilio-java-testing |
2 | 2 |
|
3 | | -[](https://github.com/twilio/twilio-java/actions/workflows/test-and-deploy.yml) |
4 | | -[](https://mvnrepository.com/artifact/com.twilio.sdk/twilio) |
5 | | -[](https://twil.io/learn-open-source) |
6 | | -[](https://libs.tech/project/307476/twilio-java) |
7 | | - |
8 | | -## Documentation |
9 | | - |
10 | | -The documentation for the Twilio API can be found [here][apidocs]. |
11 | | - |
12 | | -The Java library documentation can be found [here][libdocs]. |
13 | | - |
14 | | -## Versions |
15 | | - |
16 | | -`twilio-java` uses a modified version of [Semantic Versioning](https://semver.org) for all changes. [See this document](VERSIONS.md) for details. |
17 | | - |
18 | | -### TLS 1.2 Requirements |
19 | | - |
20 | | -New accounts and subaccounts are now required to use TLS 1.2 when accessing the REST API. ["Upgrade Required" errors](https://www.twilio.com/docs/api/errors/20426) indicate that TLS 1.0/1.1 is being used. |
21 | | - |
22 | | -### Supported Java Versions |
23 | | - |
24 | | -This library supports the following Java implementations: |
25 | | - |
26 | | -- OpenJDK 8 |
27 | | -- OpenJDK 11 |
28 | | -- OpenJDK 17 |
29 | | -- OracleJDK 8 |
30 | | -- OracleJDK 11 |
31 | | -- OracleJDK 17 |
32 | | - |
33 | | -For Java 7 support, use `twilio-java` major version `7.X.X`. |
34 | | - |
35 | | -### Beta Annotation |
36 | | - |
37 | | -To indicate that a class or method is in beta and subject to change, we use the `@Beta` annotation. For example: |
38 | | - |
39 | | -```java |
40 | | - |
41 | | -@Beta |
42 | | -public class ClassName { |
43 | | - // Class implementation |
44 | | -} |
45 | | - |
46 | | - |
47 | | -public class ClassName { |
48 | | - @Beta |
49 | | - public void init() { |
50 | | - // Implementation |
51 | | - } |
52 | | -} |
53 | | -``` |
54 | | - |
55 | | -## Installation |
56 | | - |
57 | | -`twilio-java` uses Maven. At present the jars _are_ available from a public [maven](https://mvnrepository.com/artifact/com.twilio.sdk/twilio) repository. |
58 | | - |
59 | | -Use the following dependency in your project to grab via Maven: |
60 | | - |
61 | | -```xml |
62 | | -<dependency> |
63 | | - <groupId>com.twilio.sdk</groupId> |
64 | | - <artifactId>twilio</artifactId> |
65 | | - <version>10.X.X</version> |
66 | | - <scope>compile</scope> |
67 | | -</dependency> |
68 | | -``` |
69 | | - |
70 | | -or Gradle: |
71 | | - |
72 | | -```groovy |
73 | | -implementation "com.twilio.sdk:twilio:10.X.X" |
74 | | -``` |
75 | | - |
76 | | -If you want to compile it yourself, here's how: |
77 | | - |
78 | | -```shell |
79 | | -git clone git@github.com:twilio/twilio-java |
80 | | -cd twilio-java |
81 | | -mvn install # Requires maven, download from https://maven.apache.org/download.html |
82 | | -``` |
83 | | - |
84 | | -If you want to build your own .jar, execute the following from within the cloned directory: |
85 | | - |
86 | | -```shell |
87 | | -mvn package |
88 | | -``` |
89 | | - |
90 | | -If you run into trouble with local tests, use: |
91 | | - |
92 | | -```shell |
93 | | -mvn package -Dmaven.test.skip=true |
94 | | -``` |
95 | | - |
96 | | -### Test your installation |
97 | | - |
98 | | -Try sending yourself an SMS message, like this: |
99 | | - |
100 | | -```java |
101 | | -import com.twilio.Twilio; |
102 | | -import com.twilio.rest.api.v2010.account.Message; |
103 | | -import com.twilio.type.PhoneNumber; |
104 | | - |
105 | | -public class Example { |
106 | | - |
107 | | - // Find your Account Sid and Token at console.twilio.com |
108 | | - public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; |
109 | | - public static final String AUTH_TOKEN = "your_auth_token"; |
110 | | - |
111 | | - public static void main(String[] args) { |
112 | | - Twilio.init(ACCOUNT_SID, AUTH_TOKEN); |
113 | | - |
114 | | - Message message = Message |
115 | | - .creator( |
116 | | - new PhoneNumber("+15558675309"), |
117 | | - new PhoneNumber("+15017250604"), |
118 | | - "This is the ship that made the Kessel Run in fourteen parsecs?" |
119 | | - ) |
120 | | - .create(); |
121 | | - |
122 | | - System.out.println(message.getSid()); |
123 | | - } |
124 | | -} |
125 | | -``` |
126 | | - |
127 | | -> **Warning** |
128 | | -> It's okay to hardcode your credentials when testing locally, but you should use environment variables to keep them secret before committing any code or deploying to production. Check out [How to Set Environment Variables](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html) for more information. |
129 | | -
|
130 | | -## Usage |
131 | | - |
132 | | -### Initialize the Client |
133 | | - |
134 | | -```java |
135 | | -import com.twilio.Twilio; |
136 | | -import com.twilio.exception.AuthenticationException; |
137 | | - |
138 | | -public class Example { |
139 | | - |
140 | | - private static final String ACCOUNT_SID = |
141 | | - "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; |
142 | | - private static final String AUTH_TOKEN = "your_auth_token"; |
143 | | - |
144 | | - public static void main(String[] args) throws AuthenticationException { |
145 | | - Twilio.init(ACCOUNT_SID, AUTH_TOKEN); |
146 | | - } |
147 | | -} |
148 | | -``` |
149 | | -### Initialize the client when endpoints does not use basic authentication |
150 | | -The above example shows how to initialize the client in case the endpoints use basic authentication. When the endpoint does not require any authentication, use TwilioNoAuth client instead. |
151 | | -There are endpoints like Organization domain which uses bearer token authentication. Custom Clients needs to be used in such cases and initialize them with the values required for access token generation. |
152 | | - |
153 | | -To bypass the initialization step you can also use a custom token manager implementation. Token manager class should implement the Token interface and call a token generation endpoint of your choice. |
154 | | -Detailed examples [here](https://github.com/twilio/twilio-java/tree/main/examples) |
155 | | - |
156 | | -### Environment Variables |
157 | | - |
158 | | -`twilio-java` supports the credentials, region, and edge values stored in the following environment variables: |
159 | | - |
160 | | -- `TWILIO_ACCOUNT_SID` |
161 | | -- `TWILIO_AUTH_TOKEN` |
162 | | -- `TWILIO_REGION` |
163 | | -- `TWILIO_EDGE` |
164 | | - |
165 | | -
EED3
If using these variables, the above client initialization can be skipped. |
166 | | - |
167 | | -### Make a Call |
168 | | - |
169 | | -```java |
170 | | -import com.twilio.Twilio; |
171 | | -import com.twilio.rest.api.v2010.account.Call; |
172 | | -import com.twilio.type.PhoneNumber; |
173 | | -import java.net.URI; |
174 | | -import java.net.URISyntaxException; |
175 | | - |
176 | | -public class Example { |
177 | | - |
178 | | - public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; |
179 | | - public static final String AUTH_TOKEN = "your_auth_token"; |
180 | | - |
181 | | - public static void main(String[] args) throws URISyntaxException { |
182 | | - Twilio.init(ACCOUNT_SID, AUTH_TOKEN); |
183 | | - |
184 | | - Call call = Call |
185 | | - .creator( |
186 | | - new PhoneNumber("+14155551212"), |
187 | | - new PhoneNumber("+15017250604"), |
188 | | - new URI("http://demo.twilio.com/docs/voice.xml") |
189 | | - ) |
190 | | - .create(); |
191 | | - |
192 | | - System.out.println(call.getSid()); |
193 | | - } |
194 | | -} |
195 | | -``` |
196 | | - |
197 | | -### Get an existing Call |
198 | | - |
199 | | -```java |
200 | | -import com.twilio.Twilio; |
201 | | -import com.twilio.rest.api.v2010.account.Call; |
202 | | - |
203 | | -public class Example { |
204 | | - |
205 | | - public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; |
206 | | - public static final String AUTH_TOKEN = "your_auth_token"; |
207 | | - |
208 | | - public static void main(String[] args) { |
209 | | - Twilio.init(ACCOUNT_SID, AUTH_TOKEN); |
210 | | - |
211 | | - Call call = Call.fetcher("CA42ed11f93dc08b952027ffbc406d0868").fetch(); |
212 | | - |
213 | | - System.out.println(call.getTo()); |
214 | | - } |
215 | | -} |
216 | | -``` |
217 | | - |
218 | | - |
219 | | - |
220 | | -### OAuth Feature for Twilio APIs |
221 | | -We are introducing Client Credentials Flow-based OAuth 2.0 authentication. |
222 | | -This feature is currently in `beta` and its implementation is subject to change. |
223 | | - |
224 | | -- API examples [here](https://github.com/twilio/twilio-java/blob/main/examples/FetchMessageUsingOAuth.md) |
225 | | -- Organisation API examples [here](https://github.com/twilio/twilio-java/blob/main/examples/BearerTokenAuthentication.md) |
226 | | - |
227 | | -### Iterate through records |
228 | | - |
229 | | -The library automatically handles paging for you. With the `read` method, you can specify the number of records you want to receive (`limit`) and the maximum size you want each page fetch to be (`pageSize`). The library will then handle the task for you, fetching new pages under the hood as you iterate over the records. |
230 | | - |
231 | | -For more information, view the [auto-generated library docs](https://www.twilio.com/docs/libraries/reference/twilio-java/). |
232 | | - |
233 | | -#### Use the `read` method |
234 | | - |
235 | | -```java |
236 | | -import com.twilio.Twilio; |
237 | | -import com.twilio.base.ResourceSet; |
238 | | -import com.twilio.rest.api.v2010.account.Call; |
239 | | - |
240 | | -public class Example { |
241 | | - |
242 | | - public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; |
243 | | - public static final String AUTH_TOKEN = "your_auth_token"; |
244 | | - |
245 | | - public static void main(String[] args) { |
246 | | - Twilio.init(ACCOUNT_SID, AUTH_TOKEN); |
247 | | - |
248 | | - ResourceSet<Call> calls = Call.reader().read(); |
249 | | - |
250 | | - for (Call call : calls) { |
251 | | - System.out.println(call.getDirection()); |
252 | | - } |
253 | | - } |
254 | | -} |
255 | | -``` |
256 | | - |
257 | | -### Specify Region and/or Edge |
258 | | - |
259 | | -To take advantage of Twilio's [Global Infrastructure](https://www.twilio.com/docs/global-infrastructure), specify the target Region and/or Edge for the client: |
260 | | - |
261 | | -```java |
262 | | -Twilio.init(accountSid, authToken); |
263 | | -Twilio.setRegion("au1"); |
264 | | -Twilio.setEdge("sydney"); |
265 | | -``` |
266 | | - |
267 | | -This will result in the `hostname` transforming from `api.twilio.com` to `api.sydney.au1.twilio.com`. |
268 | | - |
269 | | -### Enable Debug Logging |
270 | | - |
271 | | -This library uses SLF4J for logging. Consult the [SFL4J documentation](http://slf4j.org/docs.html) for information about logging configuration. |
272 | | - |
273 | | -For example, if you are using `log4j`: |
274 | | - |
275 | | -- Make sure you have `log4j-slf4j-impl`, `log4j-core` and `log4j-api` in your `pom.xml` file |
276 | | -- Define the logging level for the Twilio HTTP client in your configuration. For example, in `src/main/resources/log4j2.xml`: |
277 | | - |
278 | | - ```xml |
279 | | - <?xml version="1.0" encoding="UTF-8"?> |
280 | | - <Configuration status="WARN"> |
281 | | - <Appenders> |
282 | | - <Console name="Console" target="SYSTEM_OUT"> |
283 | | - <PatternLayout pattern="%d{HH:mm:ss.SSS} %-5level - %msg%n"/> |
284 | | - </Console> |
285 | | - </Appenders> |
286 | | - <Loggers> |
287 | | - <!--Your Twilio logging configuration goes here--> |
288 | | - <Logger name="com.twilio.http" level="debug" additivity="false"> |
289 | | - <AppenderRef ref="Console"/> |
290 | | - </Logger> |
291 | | - <Root level="info"> |
292 | | - <AppenderRef ref="Console"/> |
293 | | - </Root> |
294 | | - </Loggers> |
295 | | - </Configuration> |
296 | | - ``` |
297 | | - |
298 | | -### Handle Exceptions |
299 | | - |
300 | | -```java |
301 | | -import com.twilio.exception.ApiException; |
302 | | - |
303 | | -try { |
304 | | - Message message = Message.creator( |
305 | | - new PhoneNumber("+15558881234"), // To number |
306 | | - new PhoneNumber("+15559994321"), // From number |
307 | | - "Hello world!" // SMS body |
308 | | - ).create(); |
309 | | - |
310 | | - System.out.println(message.getSid()); |
311 | | -} catch (final ApiException e) { |
312 | | - System.err.println(e); |
313 | | -} |
314 | | -``` |
315 | | - |
316 | | -### Use a Client With PKCV Authentication |
317 | | - |
318 | | -Additional documentation here: https://twilio.com/docs/iam/pkcv/quickstart |
319 | | - |
320 | | -```java |
321 | | -ValidationClient httpClient = new ValidationClient(ACCOUNT_SID, key.getSid(), signingKey.getSid(), pair.getPrivate()); |
322 | | -TwilioRestClient client = new TwilioRestClient.Builder(signingKey.getSid(), signingKey.getSecret()) |
323 | | - .accountSid(ACCOUNT_SID) |
324 | | - .httpClient(httpClient) |
325 | | - .build(); |
326 | | -``` |
327 | | - |
328 | | -### Generate TwiML |
329 | | - |
330 | | -To control phone calls, your application needs to output [TwiML][twiml]. |
331 | | - |
332 | | -TwiML in twilio-java now use the builder pattern! |
333 | | - |
334 | | -```java |
335 | | -TwiML twiml = new VoiceResponse.Builder() |
336 | | - .say(new Say.Builder("Hello World!").build()) |
337 | | - .play(new Play.Builder("https://api.twilio.com/cowbell.mp3").loop(5).build()) |
338 | | - .build(); |
339 | | -``` |
340 | | - |
341 | | -That will output XML that looks like this: |
342 | | - |
343 | | -```xml |
344 | | -<Response> |
345 | | - <Say>Hello World!</Say> |
346 | | - <Play loop="5">https://api.twilio.com/cowbell.mp3</Play> |
347 | | -</Response> |
348 | | -``` |
349 | | - |
350 | | -### Use a custom HTTP Client |
351 | | - |
352 | | -To use a custom HTTP client with this helper library, please see the [advanced example of how to do so](./advanced-examples/custom-http-client.md). |
353 | | - |
354 | | -## Docker image |
355 | | - |
356 | | -The `Dockerfile` present in this repository and its respective `twilio/twilio-java` Docker image are currently used by Twilio for testing purposes only. |
357 | | - |
358 | | -## Getting Help |
359 | | - |
360 | | -If you need help installing or using the library, please check the [Twilio Support Help Center](https://support.twilio.com) first, and [file a support ticket](https://twilio.com/help/contact) if you don't find an answer to your question. |
361 | | - |
362 | | -If you've instead found a bug in the library or would like new features added, go ahead and open issues or pull requests against this repo! |
363 | | - |
364 | | -[apidocs]: https://www.twilio.com/docs/api |
365 | | -[twiml]: https://www.twilio.com/docs/api/twiml |
366 | | -[libdocs]: https://twilio.github.io/twilio-java |
| 3 | +## THIS IS TESTING RELEASE MUST NOT BE USED |
0 commit comments