Outbound PSTN Calling guide for JavaScript

In this getting started guide we'll cover adding call methods for phone numbers to the Conversation we created in the simple conversation with user calling getting started guide. We'll deal with member call events that trigger on the application and call state events that trigger on the Call object.

Concepts

This guide will introduce you to the following concepts.

  • Calls - calling a phone number from your application without creating a Conversation first

Before you begin

  • Ensure you have run through the previous guide
  • You should read the NCCO guide for calling before completing this quick start guide. In order to make an outbound PSTN call, you'll have to correctly link your application to an answer url with an NCCO. The NCCO guide goes into further detail.

1 - Update the JavaScript App

We will use the application we already created for calling users getting started guide. All the basic setup has been done in the previous guides and should be in place. We can now focus on updating the client-side application.

1.1 - Add call phone control UI

First, we'll add the UI for a user to call a phone number, and then be able to hang up. Let's add the UI at the top of the conversations area

  <section id="conversations">
    <form id="call-phone-form">
      <h1>Call phone</h1>
      <input type="text" name="phonenumber" value="">
      <input type="submit" value="Call" />
    </form>
    ...
  </section>

And add the new UI in the class constructor

constructor() {
  ...
  this.callPhoneForm = document.getElementById('call-phone-form')
}

1.2 - Add callPhone handler

All the call control UI is in place, so we'll need to add only a method for calling phones, using the callPhone method on the application. Let's update setupUserEvents with a listener for callPhoneForm:

this.callPhoneForm.addEventListener('submit', (event) => {
  event.preventDefault()

  this.app.callPhone(this.callPhoneForm.children.phonenumber.value)
})

1.3 - Open the conversation a browser window

Now run index.html in the browser, making sure to login with the user name jamie. Call a phone number, accept the call and start talking. You'll also see the call status events being logged in the browser console.

Thats's it! Your page should now look something like this  .

Where next?

Outbound PSTN Calling for iOS with Swift

In this getting started guide we'll cover how to make an outbound PSTN call from your iOS app using the Nexmo Stitch SDK.

Concepts

This guide will cover the following concepts:

  • Calls - calling a PSTN number in your application without creating a Conversation first
  • Call State - A state a call can be in. Either STARTED, RINGING, or ANSWERED

Before you begin

You should read the NCCO guide for calling before completing this quickstart. In order to make an outbound PSTN call, you'll have to correctly link your application to an answer url with an NCCO. The NCCO guide goes into further detail.

Setting up an iOS Project

To set up the Nexmo In-App to Phone Calling in iOS with Swift, you will need to setup both the UI and the methods. Here we'll program methods and then wire them up.

Programming the methods

First you'll need the latest version of the Nexmo Stitch SDK in your ViewController.swift.

import Stitch

Now that you have the SDK included in your project, you'll ned to create a new instance of the ConversationClient. You can do this in your ViewController.swift where you'll be making your outbound PSTN call.

 private var call: Call?
override func viewDidLoad() {
    super.viewDidLoad()
    ConversationClient.configuration = Configuration.init(with: .info)
    ConversationClient.instance
       .login(with: "JWT_TOKEN")
       .subscribe()
}

In this example we're assuming the user has already logged in with the conversationClient.login() method. For more details about how to implement that read the simple conversation quickstart.

@IBAction
func makeCall() {
     guard let number = textfield.text else { return }

     ConversationClient.instance.media.callPhone(number, onSuccess: { result in
         self.call = result.call

          print("DEMO - Created call")
      }) { error in
          print("DEMO - Failed to make call: \(error)")
      }
}
@IBAction
func hangup() {
     call?.hangUp(onSuccess: {
         print("DEMO - Hangup call successful")
     })
}

Programming the UI

To configure the UI were going to add two instances of UIButton below an instance of UITextField.

  • add an instance of UITextField
  • add an instance of UIButton but inside of its label, make sure to add a telephone đź“ž emoji!
  • add an instance of UIButton but inside of its label, make sure to add a stop sign 🛑 emoji!

Make sure that you wire up each one of these UI elements to their respective properties or methods.

Try it out!

After you've followed along with this quickstart, you will be able to make a call to a PSTN phone. Don't forget to include the country code when you make a call! For example if you're calling a phone number in the USA, the phone number will need to begin with a 1. When calling a phone number in Great Britain the phone number will need to be prefixed with 44.

Where next?

You can view the source code for this quickstart on GitHub  .

Outbound PSTN Calling guide for Android

In this getting started guide we'll cover how to make an outbound PSTN call from your Android app using the Nexmo Stitch SDK.

Concepts

This guide will cover the following concepts:

  • Calls - calling a PSTN number in your application without creating a Conversation first
  • Call State - A state a call can be in. Either STARTED, RINGING, or ANSWERED

Before you begin

You should read the NCCO guide for calling before completing this quickstart. In order to make an outbound PSTN call, you'll have to correctly link your application to an answer url with an NCCO. The NCCO guide goes into further detail.

Setting up an Android Project.

First you'll need the latest version of the Nexmo Stitch SDK in your app/build.gradle

implementation 'com.nexmo:stitch:3.0.0'

Now that you have the SDK included in your project, you'll need to create a new instance on the ConversationClient. You can do this in a new Activity where you'll be making the outbound PSTN call. For this purpose let's create a CallActivity with and its layout:

class CallActivity : BaseActivity() {
    private var currentCall: Call? = null
    private lateinit var client: ConversationClient

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_call)

        conversationClient = ConversationClient.ConversationClientBuilder()
                .context(context.applicationContext)
                .logLevel(Log.DEBUG)
                .onMainThread(true)
                .build()
    }
}
<?xml version="1.0" encoding="utf-8"?>
<android.support.constraint.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context="com.nexmo.stitchoutboundpstncalling.CallActivity">

    <TextView
        android:id="@+id/callStatus"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        tools:text="Calling +18675309"/>

    <EditText
        android:id="@+id/phoneNumberInput"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:inputType="phone"/>

    <Button
        android:id="@+id/callControlBtn"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginBottom="8dp"
        android:text="Call"
        app:layout_constraintBottom_toBottomOf="parent" />

</android.support.constraint.ConstraintLayout>

In this example we're assuming the user has already logged in with the conversationClient.login() method. For more details about how to implement that read the simple conversation quickstart or view the LoginActivity in the source code for this quickstart 

Making an outbound PSTN call

Now that we've set up our CallActivity we can add the PSTN calling functionality. To do this we'll need to make some changes to the Activity. First in the onCreate method let's set the click listener for the callControlBtn.

override fun onCreate(savedInstanceState: Bundle?) {
  ...
  callControlBtn.setOnClickListener { callPhone() }
}

Now that we've set up the click listener, we need to implement the callPhone() and endCall() methods:

fun callPhone() {
    val phoneNumber = phoneNumberInput.text.toString()

    conversationClient.callPhone(phoneNumber, object : RequestHandler<Call> {
        override fun onError(apiError: NexmoAPIError) {
            logAndShow("Cannot initiate call: " + apiError.message)
        }

        override fun onSuccess(result: Call) {
            currentCall = result
            callControlBtn.text = "Hangup"
            callControlBtn.setOnClickListener { endCall() }

            when (result.callState) {
                Call.CALL_STATE.STARTED -> logAndShow("Started")
                Call.CALL_STATE.RINGING -> logAndShow("Ringing")
                Call.CALL_STATE.ANSWERED -> logAndShow("Answered")
                else -> logAndShow("Error attaching call listener")
            }

        }
    })
}

private fun endCall() {
    currentCall?.hangup(object : RequestHandler<Void> {
        override fun onError(apiError: NexmoAPIError) {
            logAndShow("Cannot hangup: " + apiError.toString())
        }

        override fun onSuccess(result: Void) {
            logAndShow("Call completed.")
            runOnUiThread {
                callControlBtn.text = "Call"
                callControlBtn.setOnClickListener { callPhone() }
            }
        }
    })
}

To initiate the PSTN call, we can use the conversationClient.callPhone() method, passing in the phone number of that we want to call and handling the onSuccess and onError callbacks. If the call is successfully made we can check the Call.CALL_STATE to know when the call has been started, is ringing, or has been answered.

Hanging up on the call requires hanging on to a reference to the Call object created in the onSuccess callback of conversationClient.callPhone(). By using currentCall?.hangup the call will hung up for both the IP and PSTN user. If the call is successfully hung up, we'll set up the activity to make a new call if the user chooses.

Trying it out

After you've followed along with this quickstart, you will be able to make a call to a PSTN phone. Don't forget to include the country code when you make a call! For example if you're calling a phone number in the USA, the phone number will need to begin with a 1. When calling a phone number in Great Britain the phone number will need to be prefixed with 44.

Where next?

You can view the source code for this quickstart on GitHub