Updates: Check the release notes for new features and product updates.

Place a verified call

When your infrastructure is in place to check recipient device capabilities, register calls, and update call states (optional), and you've set up a test device, you're ready to place your first verified call.

Prerequisites

Before you place a verified call, you need to gather some information:

  • Path to your GCP project's service account key on your development machine
  • The brand phone number placing the call, in E.164 format (for example, "+12223334444")
  • The phone number for your test device, in E.164 format (for example, "+56667778888")
  • (Optional) The reason for the call

Additionally, you need the gcloud command line tool installed on your development machine.

Place the call

To place a successful verified call, run the following commands. Replace variables with values you identified in Prerequisites.

  1. Prepare your credentials.

    cURL

    export GOOGLE_APPLICATION_CREDENTIALS=PATH_TO_SERVICE_ACCOUNT_KEY
    ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
    

    Python

    import json
    import os
    import time
    import jwt
    import requests
    
    # Read the path for your service account from environment variables (make sure to set the path)
    service_account_path = os.environ.get('PATH_TO_SERVICE_ACCOUNT_KEY')
    current_time = round(time.time())
    
    # Open the json service account key
    with open(service_account_path) as f:
        service_key = json.load(f)
    
    # Prepare the payload and headers for OAuth
    payload = {
        'iss': service_key['client_email'],
        'scope': 'https://www.googleapis.com/auth/businesscommunications https://www.googleapis.com/auth/cloud-platform',
        'aud': 'https://oauth2.googleapis.com/token',
        'exp': current_time + 3600,
        'iat': current_time}
    additional_headers = {'kid': service_key['private_key']}
    
    # Encode the jwt
    signed_jwt = jwt.encode(payload, service_key['private_key'],
                                headers=additional_headers, algorithm='RS256')
    
    # Prepare the data and make the OAUTH request
    data = {
        'grant_type': 'urn:ietf:params:oauth:grant-type:jwt-bearer',
        'assertion': signed_jwt
    }
    response = requests.post('https://oauth2.googleapis.com/token', data=data)
    
    # Save the access token
    token = json.loads(response.text)['access_token']
    

    For full example see our client samples

    Java/Node.js/PHP

    For more examples see our client samples

  2. Check if the recipient can receive verified calls.

    cURL

    curl -X POST "https://businesscalls.googleapis.com/v1:checkVcallDeviceReachable" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -d "{
        'deviceNumber':'PHONE_NUMBER',
      }"
    

    Python

    headers = {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer {}'.format(token),
        }
    data = {'deviceNumber': '+16400000000'}
    
    
    response = requests.post('https://businesscalls.googleapis.com/v1:checkVcallDeviceReachable',
        headers=headers,
        data=json.dumps(data))
    print(response.content)
    

    For full example see our client samples

    Java/Node.js/PHP

    For more examples see our client samples

  3. Register the call with Verified calls.

    cURL

    curl -X POST "https://businesscalls.googleapis.com/v1:sendVcallVerification" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -d "{
        'brandNumber': 'BRAND_PHONE_NUMBER',
        'deviceNumber': 'RECIPIENT_PHONE_NUMBER',
        'callReason':'CALL_REASON',
      }"
    

    Python

    headers = {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer {}'.format(token),
    }
    
    data = {
        'brandNumber': '+16400000001',
        'deviceNumber': '+16400000000',
        'callReason': 'Test call reason.',
    }
    
    response = requests.post(
      'https://businesscalls.googleapis.com/v1:sendVcallVerification',
      headers=headers,
      data=json.dumps(data))
    print(response.content)
    

    For full example see our client samples

    Java/Node.js/PHP

    For more examples see our client samples

  4. Place the call to the recipient.

    On the recipient device, the agent's branding information displays on the incoming call screen with the call reason. Don't accept the call yet.

  5. When the call is ringing, update the call state with Verified calls. Set CALL_STATE to RINGING.

    cURL

    curl -X POST "https://businesscalls.googleapis.com/v1:sendVcallState" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -d "{
        'brandNumber': 'BRAND_PHONE_NUMBER',
        'deviceNumber': 'RECIPIENT_PHONE_NUMBER',
        'callState':'CALL_STATE',
      }"
    

    Python

    For full example see our client samples

    Java/Node.js/PHP

    For more examples see our client samples

  6. On the device, accept the call.

  7. (Optional) Now that the call is connected, update the call state with Verified calls. Set CALL_STATE to CONNECTED.

    cURL

    curl -X POST "https://businesscalls.googleapis.com/v1:sendVcallState" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -d "{
        'brandNumber': 'BRAND_PHONE_NUMBER',
        'deviceNumber': 'RECIPIENT_PHONE_NUMBER',
        'callState':'CALL_STATE',
      }"
    

    Python

    For full example see our client samples

    Java/Node.js/PHP

    For more examples see our client samples

  8. On the device, end the call.

  9. (Optional) Now that the call is ended, update the call state with Verified Calls. Set CALL_STATE to ENDED.

    cURL

    curl -X POST "https://businesscalls.googleapis.com/v1:sendVcallState" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -d "{
        'brandNumber': 'BRAND_PHONE_NUMBER',
        'deviceNumber': 'RECIPIENT_PHONE_NUMBER',
        'callState':'CALL_STATE',
      }"
    

    Python

    For full example see our client samples

    Java/Node.js/PHP

    For more examples see our client samples

You've placed your first verified call! Next, confirm that your infrastructure can detect and correctly respond to error states, such as receiving a busy signal or otherwise not being able to connect to the recipient number.

Troubleshooting

If you have issues registering, receiving, placing, or updating a verified call, make sure that your infrastructure is properly configured to make requests to the Business Calls API and that your device has the Phone app installed.

If you have additional issues, contact businesscalls-support@google.com.