When you are making app to app calls, your users do not need a phone number. Instead they are identified by the identity that you provide for the user when you generate an access token for them or when you create a push credential (as Stephan points out).

When you create an access token for your app’s user, you provide a TwiML application SID. That TwiML application defines the URL that Twilio will make a request to when placing outbound calls.

When you place a call with the Voice SDK you pass a set of params to the connect method:

HashMap<String, String> params = new HashMap<>();
params.put("to", contact.getText().toString());
ConnectOptions connectOptions = new ConnectOptions.Builder(accessToken)
    .params(params)
    .build();
Voice.connect(VoiceActivity.this, connectOptions, callListener);

You can send any params you like, in the example above we send a param called “to” with a string from an input field in the view. When you place the call, Twilio then sends those parameters to that URL set in the TwiML application.

When your application receives that webhook it needs to return TwiML to Twilio to tell Twilio what to do next. In your case, you need to return TwiML that will use <Dial> and <Client> to connect to another application. In this case, you would take the incoming param “to”, as defined above, and use it as the client identity you want to call.

<Response>
   <Dial>
     <Client>
        <Identity>IDENTITY_FROM_PARAMS</Identity>
      </Client>
    </Dial>
</Response>

That way Twilio will connect the dialling application to the receiving application identified by the identity.

I am using the Android Voice SDK to build an app where one user can call another app user. Calls can only be made to other app users (by searching their username and calling them with a simple click).

(1) In this scenario, are each users provided with a Twilio phone number?

(2) Say user A calls user B. How does Twilio know that user A is calling user B? (Both a general AND technical explanation would be really helpful here). What is the workflow from making that call to answering it?

The current documentation on the Voice API doesn’t explain its technical use in conjunction with Android except for the quickstart Android project on github. However, as this is focused more on implementation rather than technical explanation, there are a few aspects I am still trying to understand like phone numbers not seemingly being used and the other points mentioned above.