Dynamic Caller ID AND How To Make A Highly Available Pivot Script With AWS API GW

[Rick Guyton]

One thing we've been sorely missing for quite some time is the ability to quickly and easily create dynamic caller IDs for our clients. In this post I will give you a solution for how you can now do this and how to roll it out on your own! It gets a little technically dense. So I'm going to start as light as possible and then delve into the more complex parts as I go.

 

WARNING!!! These URLs are strictly for demo only! I don't recommend you use these URLs in production at all. I say this not because I foresee any  stability or scale-ability issues. Quite the opposite, this can scale to the moon and back...then back again and it bills to me. So, you have been forewarned. This costs $4 per million requests, so if you guys get too crazy with it, I may shut it down without notice. I mean it'd have to get pretty crazy, but still, at your own risk here.

 

So, here's the two functions I've implemented and how you can add them to your accounts.

.

 

Static Caller ID

https://api.telkit.tk/scid/NUMNUMBER

This feature will allow you to create callflows that calls out using alternate pre-defined numbers.

 

What you will need:

- Account ID to activate

- An auth token

- An available feature code number (check for conflicts! 80-89 seem to be safe)

- The number you'd like to "spoof"

Then, run this command from a *nix device:

Quote

curl -X PUT http://ui.zswitch.net/v2/accounts/ACCOUNTID/callflows/ -H "Content-Type:application/json" -H "X-Auth-Token:AUTHTOKEN" -d '{"data":{"flow":{"data":{"method":"GET","req_timeout":"5","req_format":"kazoo","voice_url":"https://api.telkit.tk/scid/NUMBERTOSPOOF","debug":false},"module":"pivot","children":{}},"numbers":[],"patterns":["^\\*FEATURECODE"],"contact_list":{"exclude":true}}}'

 

Takes a dial string like *80*OUTBOUNDNUMBER and calls the outbound number from the predefined spoofed number from above.

 

Fully Dynamic Caller ID

https://api.telkit.tk/dcid/

This feature will allow you to setup a feature that lets them call out under LITTERALLY any number, not just numbers that you pre-define for them.

 

What you will need:

- Account ID to activate

- An auth token

- An available feature code number (check for conflicts! 80-89 seem to be safe)

Then, run this command from a *nix device:

Quote

curl -X PUT http://ui.zswitch.net/v2/accounts/ACCOUNTID/callflows/ -H "Content-Type:application/json" -H "X-Auth-Token:AUTHTOKEN" -d '{"data":{"flow":{"data":{"method":"GET","req_timeout":"5","req_format":"kazoo","voice_url":"https://api.telkit.tk/dcid/","debug":false},"module":"pivot","children":{}},"numbers":[],"patterns":["^\\*FEATURECODE"],"contact_list":{"exclude":true}}}'

This takes a dial string like *80*SPOOFEDNUMBER*OUTBOUNDNUMBER and calls the outbound number as the spoofed number.

.

 

Getting  your auth token

If you don't know how to get an auth token, here's some instructions for that...

Run this command from a *nix box:

echo -n 'YOURUSERNAME:YOURPASSWORD' | md5sum

This will give you an MD5 for the next command...

curl -X PUT http://ui.zswitch.net/v2/user_auth -H "Content-Type:application/json" -d '{ "data" : { "credentials" : "MD5HASH", "account_name" : "ACCOUNTNAME" } }' 2> /dev/null | egrep -o '"auth_token":"([^"]|\\")*"'

This will give you an auth token.

 

Try this out, if you like it read my next three posts on how to roll each function for yourself and a few last thoughts at the end.

Edited November 18, 2017 by Rick Guyton (see edit history)

[Rick Guyton]

Creating The DCID AWS API Gateway Service

1. Create the new API inside the Amazon API Gateway Service.
   • Select New API
   • Name Your API
   • Click Create API
   • 
2. Create your first resource in your fresh new API
   • Click Actions
   • Then Click Resource
   • 
3. Name Your Resource
   • Enter your Resource name as dcid
   • Same for Resource Path
   • Click Create Resource
   •  
4. Make a new Method
   • Click Actions
   • Then, Create Method
   • 
   • Then Select GET from the drop down
   • Click the check mark
   • 
5. Setup your new method
   • Next, you will see options to setup your new method, select mock as your integration type
   • Then click save
   •  
6. Setup your method's execution
   • Fortunately, Kazoo submits and accepts JSON and these are the default formats in AWS API GW. So, there's no need to mess with the Integration Request OR Method Response. The default are good for us.
   • But, we do have work to do in Method Request and Integration Response. I'll break these into separate sections though.
   •   
7. Setting up the Method Request
   • Click the method request (reference Step 6) 
   • Under Request Validator, select Validate query string parameters and headers.
   • Then, click the check mark.
   • Next, click Add Query String
   •  
   • Enter "To" as your query string name
   • Click the check mark
   • 
   • Next, click the required check box on your TO query string
   • This wraps up your Method Request, Click the <- Method Execution link to go back to the screen in step 6
   • 
8. Setting Up The Integration Response
   • Expand the 200 HTTP status
   • Expand Body Mapping Templates
   • Select The application/json Content Type
   • Paste The Script at the bottom of this post here
   • Click Save
   •  
9. DEPLOY!!!
   • Click Actions
   • Then click Deploy API
   •  
   • Select New Stage for deployment stage
   • Name your stage (I picked v1, but it could be anything)
   • Finally Click Save
   • 
10. Finally, you will be re-directed to your stage editor. You can now use your invoke URL for your very own pivot DCID!

DCID Template:

## This API assumes a format of *SOMEFEATURECODE*SpoofedCID*DestNum
## Here we split out the CID to spoof and the destination number
#set($SplitCIDString = $input.params('To').split("\*"))
## And, now we return it to Kazoo in a format it knows how to use
{
  "children": {
    "_": {
      "data": {
        "to_did": "$SplitCIDString[3]",
        "use_local_resources": false
      },
      "module": "resources"
    }
  },
  "data": {
    "caller_id_number": "$SplitCIDString[2]"
  },
  "module": "set_cid"
}

 

Edited November 17, 2017 by Rick Guyton (see edit history)

[Rick Guyton]

Creating The SCID AWS API Gateway Service

1. We will be using the same API as before, so go into your Demo API (or whatever you called it) and click on resources. We'll start there. You should see your dcid resource from the previous section. We won't be doing anything more with dcid, but I just want to be sure you are in the right place.
   • 
2. Create your second resource
   • Click Actions
   • Then Click Resource
   • 
3. Name Your Resource
   • Enter your Resource name as dcid
   • Same for Resource Path
   • Click Create Resource
   •  
4. Create a child resource under the scid resource
   • Make sure scid is highlighted
   • Click actions
   • Then click create resource
   • 
5. Name Your Child Resource
   • Enter your Resource name as number
   • VERY IMPORTANT!! Enter your Resource Path as {number}. EXACTLY!
   • Click Create Resource
   • 
6. Make a new Method
   • Click Actions
   • Then, Create Method
   • 
   • Then Select GET from the drop down
   • Click the check mark
   • 
7. Next, follow steps 4-8 in the above post on dcid. Obviously use the code block from this post when you get to step 8. You should end up with something that looks like this:
   •  
8. Re-deploy your API!
   • Click Actions
   • Then click Deploy API
   •  
   • Select your existing stage you created in the previous post
   • And hit deploy!
   • 

SCID Template:

## The destination number we get from Kazoo still has the feature
## code attached to it. So, we need to strip it off.
## The feature code must end with a *. So, here, we split the
## the string on *s, take the array size and subtract one.
## this will give us the vaule after the final * sign, our number
## to dial.
#set($SplitNum = $input.params('To').split("\*"))
#set($DestNumIndex = $SplitNum.size() - 1)
#set($NumToCall = $SplitNum[$DestNumIndex])
## After we have that, it gets pretty easy.
## Now we just present it back to Kazoo in a way it expects.
{
  "children": {
    "_": {
      "data": {
        "to_did": "$NumToCall",
        "use_local_resources": false
      },
      "module": "resources"
    }
  },
  "data": {
    "caller_id_number": "$input.params('number')"
  },
  "module": "set_cid"
}

Thats it! There's a few things you might still want to do, like test your APIs and change the URL. I'll touch on those in my last post.

Edited November 18, 2017 by Rick Guyton (see edit history)

[Rick Guyton]

Wrap Up

Why AWS API Gateway?

Well, API gateway is incredibly reliable and has nearly infinite horizontal scalability. It's also stupidly cheap. Just $4 per MILLION transactions when using Mock integrations. But, equally important to me was the Lambda functions you can trigger. With Lambda, you can execute C#, Java, Node.js or Python scripts in response to API calls. No servers, no maintenance, nearly infinite scalability and you only pay for your AWS GW fee and the time (to the second) that your code snipit takes to run. It's awesome.

Why the mock integration?

As far as I can tell, mock is free to use. As opposed to running a lambda script. Sure, the lambda script is super cheap. But, why do that when you can have free? For these API functions, all the data we need is given to us by Kazoo. It's just a minor reformatting of the data that we need. And this is a perfect use case for mock.

Testing your APIs

If you click on the GET method of either of these API functions I've provided you with, you will see a blue lightning bolt icon. Click that, can you will be able to provide your API functions with test data to see how they behave. This works with any AWS API query, not just mock ones. Very useful when developing new functions!

Custom Domain

If you want to use your own custom domain like I did with telkit.tk, follow these instructions: http://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-custom-domains.html. Otherwise, you can just use the URI provided by AWS. It will work equally well either way.

Last Note

The real intention behind this post is to cut the FUD behind using pivots in general and in using AWS GW. I'm very much hoping this tutorial makes it easier for you all to develop your own AWS API GW functions. Maybe even share them! Pivots are an insanely powerful tool that I think don't get enough attention. Have fun!!

Edited November 18, 2017 by Rick Guyton (see edit history)

[Karl Stallknecht]

Wow, thanks! This is awesome!!!

So how do we host this ourselves?

[Rick Guyton]

Just now, Karl Stallknecht said:

Wow, thanks! This is awesome!!!

So how do we host this ourselves?

Stay tuned, I was going to put it into the main post. But it took a lot longer to write that then expected. I’ll update with that next week.

[Rick Guyton]

SCID and DCIS instructions are up!

I'll post some wrap up stuff next week.

 

EDIT: Meh, was stuck working tonight anyway and I'm waiting on a huge SQL query to finish, so I just decided to bang this all out.

Edited November 18, 2017 by Rick Guyton (see edit history)

[FASTDEVICE]

If anyone is interested in rolling your own version of Rick's Dynamic CallerID and hosting yourself @Karl Stallknecht, I coded it up in PHP and published on my GitHub.

Please google "github fastdevice" and look under Pivot-ToolKit