This function can be used to interactively check whether the phone number a user has entered on a web form is not only a valid phone number, but also actually belongs to that user.
It does this by making a call to that number and interacting with the user.
There are two modes of operation; you may choose whichever you prefer:
Realtime webhooks can be sent to a URL you supply (optional in "say" mode, required in "read_dtmf" mode). This allows you to present realtime status information to the user if you wish, such as a message saying "Calling ...", and then "Ringing ..." etc to make this a truly interactive experience.
See also:
telecoms.ddi.checktelecoms.num.validate| arg | required? | syntax | info |
|---|---|---|---|
ddi | Y | TelNum | the phone number to be checked |
custID | N | posint | the customer account that will be charged for the test call (default is the account of the current API user) |
cli | Y | TelNum | The number the user will see as the calling number whilst making the test call to them |
type | N | enum:say|read_dtmf | the operating mode you want to use; default="say" |
PIN | Y | unsint | The PIN the user must enter in order to validate their number; min length 1 digit, max length 10 digits |
entry_attempts | N | posint | only applicable to "read_dtmf" mode; how many attempts the user is given in order to correctly enter the PIN before the call is ended; min value=1, max value=10 |
ref | N | string | a ref string that will be included in an extra field in the webhooks; max length 45 characters |
callbackURL | Y (if type=read_dtmf) | url.http | the http or https URL of your endpoint where realtime webhooks will be sent detailing call events |
callback_format | N | enum:JSON|URLENC | the format that the realtime webhook data will be posted in (default JSON) |
full_callback_data | N | boolean | Whether to provide additional detail in realtime webhooks; 1=yes, 0=no. Default=0 (no) |
secret_salt | N | string | if supplied, a salted checksum will be included in the realtime webhooks to help security |
When calling the user to verify their number, the number in the cli argument will be shown as the calling
number. This must be a number on your account, and cannot be a premium rate number.
This argument determines which type of telecaptha to create.
When type is "say" (or not specified), then the user will be called and the PIN will be audibly read out
to them over the phone. The user then has to enter this PIN into your web form. Your own web site code will then need
to compare what the user entered with the PIN that it supplied in the PIN
argument to telecoms.telecaptcha.create.
When type is "read_dtmf", then the user will be called and hear and audio prompt asking them to enter the PIN. The user should then use the telephone keypad to enter the PIN they were shown on your web form. Your web site code will need to analyse the webhooks in order to know whether the PIN has been entered successfully.
Telecaptcha "say" is simpler to implement as it doesn't require the use of webhooks unless you also want to show realtime call events to the user on screen. Telecaptcha "read_dtmf" cannot work without proper and timely processing of webhooks.
Your code should generate a random PIN between 1 and 10 digits and supply this in the PIN argument.
The user must enter this PIN correctly.
This argument is optional with telecaptcha "say" but mandatory with telcaptcha "read_dtmf".
In this argument you should enter the URL to where you want realtime webhooks to be sent. These webhooks notify your site in real time as call events happen. See below for format and examples of call events.
This argument is optional with telecaptcha "say" but mandatory with telcaptcha "read_dtmf".
In this argument you should enter the URL to where you want realtime webhooks to be sent. These webhooks notify your site in real time as call events happen. See below for format and examples of call events.
By default, the webhooks contain minimal data - just enough for you to be able to provide realtime feedback if required.
If you supply 1 in this argument, the webhooks will contain additional data about the call.
See further down for webhook data format.
This is a security/validation option.
When you supply a secret salt here, the webhooks will include a chksum field which your scripts
can double check in order to be sure that the callback came from us.
The checksum is calculated by doing an MD5 checksum of the string XXXYYYZZZ where XXX is the value in the
uniqueID field, YYY is the value in the seq field and ZZZ is the value you supplied
in the secret_salt argument.
For example, if uniqueID had the value 1234567890.12345_11, seq had
the value 4 and the secret_salt you supplied was grassyfields then for that webhook
the chksum field would contain the MD5 checksum of 1234567890.12345_114grassyfields,
which is 5e4fe817db6e255de3d4ef13b2334492.
There are no return values to the initial API call other than an indication of successful job submission, or any immediate errors (eg syntax errors in arguments). The result of a successful submission is as below:
All results of the telecaptcha call are returned in the webhook data. That being said, if you're just using telecaptcha "say" then you don't strictly need to monitor the webhooks at all - it may be sufficient to just see whether the user enters the correct PIN into the web form.
Having said the above, the webhooks are still required if you want to present the user with realtime information, which may be useful, especially if for example they entered a wrong number and it came back number unallocated, busy, etc. Or, if it went directly to voicemail the webhooks would show the call as answered; the user may realise what has happened and take steps to remedy that and try again.
Use telecoms.telecaptcha.create to verify the number 01134960000 that the user has
entered into the web form as their phone number.
Your system generates a random PIN (but doesn't show it to the user). It supplies this pin to
telecoms.telecaptcha.create in "say" mode. The system will call the
number that the user supplied and read out that PIN to them. The user should then enter that
PIN into the web form.
You have requested realtime webhooks to be sent to https://mysite.example.com/signup/callback?64bfe45adfc4305a49d7a44d8e9c0.
The user will see the call coming from 01632968765.
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.telecaptcha.create",
"args" : {
"ddi" : "01134960000",
"PIN" : 50834,
"callbackURL" : "https://mysite.example.com/signup/callback?64bfe45adfc4305a49d7a44d8e9c0",
"callback_format" : "JSON",
"cli" : "01632968765",
"type" : "say"
}
}
JSON example response:
{
"results" : {},
"success" : 1
}
Note that the immediate API response (above) just indicates a successful job submission.
Webhooks generated:
{"uniqueID":"1690300253.3721099_12", "seq":1, "status.tech":"init", "status.eng":"Preparing"}
{"uniqueID":"1690300253.3721099_12", "seq":2, "status.tech":"dial.01134960000", "status.eng":"Calling 01134960000"}
{"uniqueID":"1690300253.3721099_12", "seq":3, "status.tech":"ringing", "status.eng":"Ringing"}
{"uniqueID":"1690300253.3721099_12", "seq":4, "status.tech":"progress", "status.eng":"Ringing"}
{"uniqueID":"1690300253.3721099_12", "seq":5, "status.tech":"answered", "status.eng":"Answered"}
{"uniqueID":"1690300253.3721099_12", "seq":6, "status.tech":"end.OK", "status.eng":"Call ended"}
This call generated 6 seperate webhooks, which were sent in real-time as call events happened.
Each webhook contains the following fields:
uniqueID - an identifier for the call. All webhooks for a given call will have the same value in this field, but no other calls will share this value.seq - webhook sequence number. This indicates the correct order of events within a call. The first webhook will have a sequence number of 1 and will count up from there. Sometimes webhooks can arrive out of order; the sequence number indicates the true order.status.tech - a technical reason/keyword indicating what event the webhook is describing. This is intended to be used programatically.status.eng - a more user friendly English version of status.tech that is more suitable to show to a user.
The same as Example 1, except that this is done in read_dtmf mode. This means that the caller
will be played a voice prompt asking them to enter their PIN. The user should then entier their PIN on the
telephone keypad.
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.telecaptcha.create",
"args" : {
"ddi" : "01134960000",
"PIN" : 114075,
"callbackURL" : "https://mysite.example.com/signup/callback?64bfe45adfc4305a49d7a44d8e9c0",
"callback_format" : "JSON",
"cli" : "01632968765",
"type" : "read_dtmf",
"entry_attempts":3
}
}
JSON example response:
{
"results" : {},
"success" : 1
}
Note that the immediate API response (above) just indicates a successful job submission.
Webhooks generated:
{"uniqueID":"1690551123.3494066_16","seq":1,"status.tech":"init","status.eng":"Preparing"}
{"uniqueID":"1690551123.3494066_16","seq":2,"status.tech":"dial.01134960000","status.eng":"Calling 01134960000"}
{"uniqueID":"1690551123.3494066_16","seq":3,"status.tech":"ringing","status.eng":"Ringing"}
{"uniqueID":"1690551123.3494066_16","seq":4,"status.tech":"progress","status.eng":"Ringing"}
{"uniqueID":"1690551123.3494066_16","seq":5,"status.tech":"answered","status.eng":"Answered"}
{"uniqueID":"1690551123.3494066_16","seq":6,"status.tech":"input.wait","status.eng":"Waiting for input"}
{"uniqueID":"1690551123.3494066_16","seq":7,"status.tech":"input.1","status.eng":"Received digits 1"}
{"uniqueID":"1690551123.3494066_16","seq":8,"status.tech":"input.11","status.eng":"Received digits 11"}
{"uniqueID":"1690551123.3494066_16","seq":9,"status.tech":"input.114","status.eng":"Received digits 114"}
{"uniqueID":"1690551123.3494066_16","seq":10,"status.tech":"input.1140","status.eng":"Received digits 1140"}
{"uniqueID":"1690551123.3494066_16","seq":11,"status.tech":"input.11407","status.eng":"Received digits 11407"}
{"uniqueID":"1690551123.3494066_16","seq":12,"status.tech":"input.114075.ok","PINverified":1,"status.eng":"Received digits 114075 - PIN verified"}
{"uniqueID":"1690551123.3494066_16","seq":13,"status.tech":"end.OK","status.eng":"PIN verified successfully; call ended","PINverified":1}
In the above webhooks, you can see that at
11. The digits so far entered are shown in part of the machine-parseable status.tech field, and also in the human friendly status.eng field.PINverified with a value of 1 which indicates that the PIN has been verified successfully.PINverified field for convenience.The same as Example 2, except this time the user kept entering the wrong PIN.
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.telecaptcha.create",
"args" : {
"ddi" : "01134960000",
"PIN" : 114075,
"callbackURL" : "https://mysite.example.com/signup/callback?64bfe45adfc4305a49d7a44d8e9c0",
"callback_format" : "JSON",
"cli" : "01632968765",
"type" : "read_dtmf",
"entry_attempts":3
}
}
JSON example response:
{
"results" : {},
"success" : 1
}
Note that the immediate API response (above) just indicates a successful job submission.
Webhooks generated:
{"uniqueID":"1690551761.3755608_15","seq":1,"status.tech":"init","status.eng":"Preparing"}
{"uniqueID":"1690551761.3755608_15","seq":2,"status.tech":"dial.01974272014","status.eng":"Calling 01974272014"}
{"uniqueID":"1690551761.3755608_15","seq":3,"status.tech":"progress","status.eng":"Ringing"}
{"uniqueID":"1690551761.3755608_15","seq":4,"status.tech":"ringing","status.eng":"Ringing"}
{"uniqueID":"1690551761.3755608_15","seq":5,"status.tech":"answered","status.eng":"Answered"}
{"uniqueID":"1690551761.3755608_15","seq":6,"status.tech":"input.wait","status.eng":"Waiting for input"}
{"uniqueID":"1690551761.3755608_15","seq":7,"status.tech":"input.1","status.eng":"Received digits 1"}
{"uniqueID":"1690551761.3755608_15","seq":8,"status.tech":"input.12","status.eng":"Received digits 12"}
{"uniqueID":"1690551761.3755608_15","seq":9,"status.tech":"input.123","status.eng":"Received digits 123"}
{"uniqueID":"1690551761.3755608_15","seq":10,"status.tech":"input.1234","status.eng":"Received digits 1234"}
{"uniqueID":"1690551761.3755608_15","seq":11,"status.tech":"input.12345","status.eng":"Received digits 12345"}
{"uniqueID":"1690551761.3755608_15","seq":12,"status.tech":"input.123456.wrongPIN.retries=2","status.eng":"Received digits 123456 - PIN incorrect; please try again"}
{"uniqueID":"1690551761.3755608_15","seq":13,"status.tech":"input.wait","status.eng":"Waiting for input"}
{"uniqueID":"1690551761.3755608_15","seq":14,"status.tech":"input.4","status.eng":"Received digits 4"}
{"uniqueID":"1690551761.3755608_15","seq":15,"status.tech":"input.45","status.eng":"Received digits 45"}
{"uniqueID":"1690551761.3755608_15","seq":16,"status.tech":"input.456","status.eng":"Received digits 456"}
{"uniqueID":"1690551761.3755608_15","seq":17,"status.tech":"input.4567","status.eng":"Received digits 4567"}
{"uniqueID":"1690551761.3755608_15","seq":18,"status.tech":"input.45678","status.eng":"Received digits 45678"}
{"uniqueID":"1690551761.3755608_15","seq":19,"status.tech":"input.456789.wrongPIN.retries=1","status.eng":"Received digits 456789 - PIN incorrect; please try again"}
{"uniqueID":"1690551761.3755608_15","seq":20,"status.tech":"input.wait","status.eng":"Waiting for input"}
{"uniqueID":"1690551761.3755608_15","seq":21,"status.tech":"input.4","status.eng":"Received digits 4"}
{"uniqueID":"1690551761.3755608_15","seq":22,"status.tech":"input.45","status.eng":"Received digits 45"}
{"uniqueID":"1690551761.3755608_15","seq":23,"status.tech":"input.456","status.eng":"Received digits 456"}
{"uniqueID":"1690551761.3755608_15","seq":24,"status.tech":"input.4561","status.eng":"Received digits 4561"}
{"uniqueID":"1690551761.3755608_15","seq":25,"status.tech":"input.45612","status.eng":"Received digits 45612"}
{"uniqueID":"1690551761.3755608_15","seq":26,"status.tech":"input.456123.wrongPIN","status.eng":"Received digits 456123 - PIN incorrect"}
{"uniqueID":"1690551761.3755608_15","seq":27,"status.tech":"end.fail.user.wrongPIN","status.eng":"Verification failure; call ended","PINverified":0}
In the above webhooks, you can see that at
1status.tech with a value of input.123456.wrongPIN.retries=2 which means that:
input - this webhook is about user input123456 - this is what the user enteredwrongPIN - this tells you that the PIN is incorrectretries=2 - this tells you that the user has 2 more attempts remaining in this callPINverified having the value 0 but also status.tech having the value end.fail.user.wrongPIN, where
end - this webhook represents the end of the callfail - there was failure to verify the PINuser - the failure was because of the user (ie not a technical problem with making the call)wrongPIN - the PIN was incorrectThe same as Example 2, except this time the user failed to enter anything the first two times, then only entered 2 digits before everything timed out.
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.telecaptcha.create",
"args" : {
"ddi" : "01134960000",
"PIN" : 114075,
"callbackURL" : "https://mysite.example.com/signup/callback?64bfe45adfc4305a49d7a44d8e9c0",
"callback_format" : "JSON",
"cli" : "01632968765",
"type" : "read_dtmf",
"entry_attempts":3
}
}
JSON example response:
{
"results" : {},
"success" : 1
}
Note that the immediate API response (above) just indicates a successful job submission.
Webhooks generated:
{"uniqueID":"1690552947.3785005_13","seq":1,"status.tech":"init","status.eng":"Preparing"}
{"uniqueID":"1690552947.3785005_13","seq":2,"status.tech":"dial.01974272014","status.eng":"Calling 01974272014"}
{"uniqueID":"1690552947.3785005_13","seq":3,"status.tech":"progress","status.eng":"Ringing"}
{"uniqueID":"1690552947.3785005_13","seq":4,"status.tech":"ringing","status.eng":"Ringing"}
{"uniqueID":"1690552947.3785005_13","seq":5,"status.tech":"answered","status.eng":"Answered"}
{"uniqueID":"1690552947.3785005_13","seq":6,"status.tech":"input.wait","status.eng":"Waiting for input"}
{"uniqueID":"1690552947.3785005_13","seq":7,"status.tech":"input.none.timeout.retries=2","status.eng":"No digits received (input timeout); please try again"}
{"uniqueID":"1690552947.3785005_13","seq":8,"status.tech":"input.wait","status.eng":"Waiting for input"}
{"uniqueID":"1690552947.3785005_13","seq":9,"status.tech":"input.none.timeout.retries=1","status.eng":"No digits received (input timeout); please try again"}
{"uniqueID":"1690552947.3785005_13","seq":10,"status.tech":"input.wait","status.eng":"Waiting for input"}
{"uniqueID":"1690552947.3785005_13","seq":11,"status.tech":"input.1","status.eng":"Received digits 1"}
{"uniqueID":"1690552947.3785005_13","seq":12,"status.tech":"input.12","status.eng":"Received digits 12"}
{"uniqueID":"1690552947.3785005_13","seq":13,"status.tech":"input.12.timeout","status.eng":"Received digits 12 - PIN incorrect (input timeout)"}
{"uniqueID":"1690552947.3785005_13","seq":14,"status.tech":"end.fail.user.timeout","status.eng":"Verification failure; call ended","PINverified":0}
In the above webhooks, you can see that at
status.tech with a value of input.none.timeout.retries=2 which means that:
input - this webhook is about user inputnone - no digits were enteredtimeout - the system timed out whilst waiting for inputretries=2 - this tells you that the user has 2 more attempts remaining in this call1 2.status.tech having the value input.12.timeout tells you that
input - this webhook represents user input12 - the user had entered digits 1 2 (which is fewer digits than the PIN contains)timeout - the system timed out before the user entered any more digitsPINverified having the value 0 but also status.tech having the value end.fail.user.timeout tells you that
end - this webhook represents the end of the callfail - there was failure to verify the PINuser - the failure was because of the user (ie not a technical problem with making the call)timeout - the user didn't enter sufficient digits before the system gave up waiting and timed outOn this occasion, the number being tested is busy.
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.telecaptcha.create",
"args" : {
"ddi" : "01134960000",
"PIN" : 50834,
"callbackURL" : "https://mysite.example.com/signup/callback?64bfe45adfc4305a49d7a44d8e9c0",
"callback_format" : "JSON",
"cli" : "01632968765",
"type" : "say"
}
}
JSON example response:
{
"results" : {},
"success" : 1
}
Note that the immediate API response (above) just indicates a successful job submission.
Webhooks generated:
{"uniqueID":"1690554436.2534496_17","seq":1,"status.tech":"init","status.eng":"Preparing"}
{"uniqueID":"1690554436.2534496_17","seq":2,"status.tech":"dial.01134960000","status.eng":"Calling 01134960000"}
{"uniqueID":"1690554436.2534496_17","seq":3,"status.tech":"end.fail.tel.busy.17","status.eng":"Call failed: line engaged","PINverified":0}
The last webhook tells you that the call failed because the line was busy. You can tell this by status.tech having the value of end.fail.tel.busy.17, which means that:
end - this webhook represents the end of the callfail - the PIN verification failedtel - the failure was due to a telephony, not user, problembusy - the problem was that the line was busy17 - this is the Q.850 clear cause for the call (where 17 means line busy)Here, the user had entered a number that is in a number range that is not in use. There are no webhooks generated here because no actual call was made.
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.telecaptcha.create",
"args" : {
"ddi" : "02920180239",
"PIN" : 50834,
"callbackURL" : "https://mysite.example.com/signup/callback?64bfe45adfc4305a49d7a44d8e9c0",
"callback_format" : "JSON",
"cli" : "01632968765",
"type" : "say"
}
}
JSON example response:
{
"success" : 0,
"error" : "number non-valid",
"errordiags" : {
"arg" : "number",
"badval" : "01134960000",
"errclass" : "syntax",
"errtype" : "perm",
"info" : "number not in use",
"syntax" : "TelNumExt(complete)"
},
"errornum" : "5.1.3",
"results" : {}
}
status.tech values
In webhooks, status.tech can have these possible values:
init - the call is initialising; this is the first indication that the call is actually happening.dial.NNNN - the system is dialling number NNNNringing - the system has received indication that the phone is ringingprogress - the system has received indication of session progress (similar to ringing - can be assumed to be the same thing in many cases)answered - the call has been answeredend.fail.user.rejected - call ended; the call was rejectedend.fail.tel.KEYWORD.CAUSE - the call ended without successfully connecting. The most common values of KEYWORD.CAUSE are:
unalloc.1 - unallocated number (ie number not in use)noroute.2 - no route to transit network (ie fault on the telephone network)noroute.3 - no route to destination (ie fault on the telephone network)noans.16 - no answer - call (probably) rang but nobody picked upbusy.17 - number engaged/busynoresp.18 - no user responding (telephony network ended the call)noans.19 - no answer from user (telephony network ended the call)absent.20 - subscriber absentrej.21 - call rejectednumchanged.22 - number has been changedabandoned.26 - Non-selected user clearing (the user has not been awarded the incoming call) - eg for a non-winning callee with parallel diallingooo.27 - destination out of ordernumshort.28 - invalid number format (number too short)rej.29 - facility rejectedunspec.31 - normal, unspecified (misc telephony network issue)nochan.34 - no circuit/channel available (misc telephony network issue)netooo.38 - network out of ordertemp.41 - temporary failureconj.42 - congestion (telephony network issue)nobearer.58 - bearer capacity not presently available (telephony network issue)notimp.66 - channel type not implemented (telephony network issue)timerexp.102 - recovery on timer expired (telephony network issue)unspec.127 - internetworking, unspecified (telephony network issue)read_dtmf mode:
input.wait - the system has played the audio prompt to the user and is now waiting for them to start keying in PIN digits on their telephone keypadinput.XXX - sent when the user presses a button on their keypard; XXX shows the digits entered so far on this attemptinput.XXXXXX.ok - the user has finished entering the PIN (which will be shown in place of XXXXXX); the PIN entry matched the expected valueinput.none - the user didn't enter any digits and the system timed outinput.XXXX.timeout - the user entered digits XXXX, more were required but they paused and the system timed outinput.XXXXXX.wrongPIN - the user entered the PIN incorrectlyinput.XXX.timeout.retries=Y - the user entered digits XXX before the system timed out. They have Y remaining attempts so the system will re-prompt them for the PIN and try again.input.XXXXXX.wrongPIN.retries=Y - the user entered the wrong PIN. They have Y remaining attempts so the system will re-prompt them for the PIN and try again.end.OK - call ended; user entered the PIN successfully.end.fail.user - call ended; the call was answered but the user failed to correctly enter the PIN.