sparkjava-demo-enterprise-integration

Telnyx Java Getting Started

Sample application demonstrating Java SDK Basics

Documentation & Tutorial

The full documentation and tutorial is available on developers.telnyx.com

Pre-Reqs

You will need to set up:

• Telnyx Account
• Telnyx Phone Number enabled with:
  • Telnyx Call Control Application
  • Telnyx Outbound Voice Profile
• Ability to receive webhooks (with something like ngrok)
• Java installed

What you can do

• Send a text message and inspect the DLR response
• Send a search request to look for available Numbers (limits to 2)
• Pass an optional query parameter reserve=true to reserve the numbers
• Create a phone number order

Usage

The following environmental variables need to be set

Variable	Description
TELNYX_API_KEY	Your Telnyx API Key
TELNYX_PUBLIC_KEY	Your Telnyx Public Key
TELNYX_APP_PORT	Defaults to 8000 The port the app will be served

.env file

This app uses the excellent java dotenv package to manage environment variables.

Make a copy of .env.sample and save as .env and update the variables to match your creds.

TELNYX_API_KEY=
TELNYX_PUBLIC_KEY=
TENYX_APP_PORT=8000

Callback URLs For Telnyx Applications

Callback Type	URL
Inbound Voice Callback	{ngrok-url}/Callbacks/Voice/Inbound
Inbound Message Callback	{ngrok-url}/Callbacks/Messaging/Inbound
Outbound Message Status Callback	{ngrok-url}/Callbacks/Messaging/Outbound

Install

Run the following commands to get started

$ git clone https://github.com/d-telnyx/demo-java-telnyx.git

Ngrok

This application is served on the port defined in the runtime environment (or in the .env file). Be sure to launch ngrok for that port

./ngrok http 8000

Terminal should look something like

ngrok by @inconshreveable                                                                                                                               (Ctrl+C to quit)

Session Status                online
Account                       Little Bobby Tables (Plan: Free)
Version                       2.3.35
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://your-url.ngrok.io -> http://localhost:8000
Forwarding                    https://your-url.ngrok.io -> http://localhost:8000

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

At this point you can point your application to generated ngrok URL + path (Example: http://{your-url}.ngrok.io/Callbacks/Voice/Inbound).

Run

Open your IDE and run the application

API Docs

Sending Messages

Send a POST request to http://{your-url}.ngrok.io/SendMessage and the Server will proxy the request to your Telnyx account

Parameter	Description	Example
to	The destination phone number	+19198675309
from	The Telnyx phone number	+191976429067
text	The actual message content	hello world 👋

POST http://your-url.ngrok.io/SendMessage HTTP/1.1
Content-Type: application/json; charset=utf-8

{
    "to": "+19198675309",
    "from": "+191976429067",
    "text": "hello world 👋"
}

Searching Phone numbers

Send a GET request to http://{your-url}.ngrok.io/availableNumbers and the Server will proxy the request to your Telnyx account

Query Parameter	Description	Example	Required
countryCode	The country searching	US	True
state	The Canadian Province or US State	NC	True
city	The city	Raleigh	True
reserve	Boolean value to reserve the found numbers	true	False

⚠️ passing reserve=true will change the response payload from availableNumbers response to reservation response

Example 1 of 2: Search Raleigh, NC phone numbers

GET http://your-url.ngrok.io/availableNumbers?countryCode=US&city=Raleigh&state=NC HTTP/1.1

Example 2 of 2: Search AND RESERVE Raleigh, NC phone numbers

GET http://your-url.ngrok.io/availableNumbers?countryCode=US&city=Raleigh&state=NC?reserve=true HTTP/1.1

Ordering Phone numbers

Send a POST request to http://{your-url}.ngrok.io/availableNumbers and the Server will proxy the request to your Telnyx account

Parameter	Description	Example
phoneNumber	The desired phone number to order	+19198675309

POST http://your-url.ngrok.io/availableNumbers HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "phoneNumber": "+19198675309"
}

Next Steps