Generate InstaCall Buttons with the OnSIP  Admin API

While it is possible to manually construct an InstaCall button HTML, the InstaCall Generate action can be used to generate the code conveniently using the OnSIP Admin API. This guide covers several common configurations for InstaCall buttons and generating the button codes for those configurations.

Authenticated OnSIP User Destination

The most common destination SIP address for an InstaCall button is an authenticated OnSIP user. With this configuration, you can create a “Click to Call Me” button. Then, registering with a user agent such as the SIP.js Demo Phone, you can receive calls from InstaCall users.

ParametersValue
CallDestination Your SIP address (e.g. john.doe@example.onsip.com)
CallerId "caller-name", to prompt the visitor for their name.
ButtonText “Click to Call {Your Name}” (e.g, “Click to Call John Doe”)
FromURI Blank. Authentication is enabled in this domain, so an anonymous SIP address should be used.

Using John Doe as an example, here is what the API call could look like using cURL:

1
2
3
4
5
curl -X POST \
--user john.doe@example.onsip.com:mysuperpassword \
--data \
'Action=InstacallGenerate&InstacallName=ExampleOne&OrganizationId=12345&CallDestination=john.doe%40example.onsip.com&CallerId=caller-name&ButtonText=Click to Call John Doe' \
https://api.onsip.com/api

Sample response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
<?xml version="1.0" encoding="UTF-8"?>
<Response xmlns="http://www.jnctn.net/ns/rest/2006-01">
  <Context>
    <Action>
      <IsCompleted>true</IsCompleted>
    </Action>
    <Request>
      <IsValid>true</IsValid>
      <DateTime>2014-04-16T16:04:27+00:00</DateTime>
      <Duration>50</Duration>
      <Parameters>
        <Parameter>
          <Name>Action</Name>
          <Value>InstacallGenerate</Value>
        </Parameter>
        <Parameter>
          <Name>InstacallName</Name>
          <Value>ExampleOne</Value>
        </Parameter>
        <Parameter>
          <Name>OrganizationId</Name>
          <Value>12345</Value>
        </Parameter>
        <Parameter>
          <Name>CallDestination</Name>
          <Value>john.doe@example.onsip.com</Value>
        </Parameter>
        <Parameter>
          <Name>CallerId</Name>
          <Value>caller-name</Value>
        </Parameter>
        <Parameter>
          <Name>ButtonText</Name>
          <Value>Click to Call John Doe</Value>
        </Parameter>
        <Parameter>
          <Name>VideoEnabled</Name>
          <Value>true</Value>
        </Parameter>
        <Parameter>
          <Name>DtmfEnabled</Name>
          <Value>true</Value>
        </Parameter>
        <Parameter>
          <Name>RemoveLogo</Name>
          <Value>false</Value>
        </Parameter>
        <Parameter>
          <Name>Theme</Name>
          <Value>flat-light</Value>
        </Parameter>
      </Parameters>
    </Request>
    <Session>
      <Stateless>true</Stateless>
      <IsEstablished>true</IsEstablished>
      <SessionId>9921c554c48ba60417a8dac8edbbe611</SessionId>
      <UserId>54321</UserId>
      <Roles>
        <Role>
          <Name>Account Admin</Name>
        </Role>
      </Roles>
    </Session>
  </Context>
  <Result>
    <InstacallGenerate>
      <Instacall>
        <InstacallId/>
        <InstacallName>ExampleOne</InstacallName>
        <Instructions>Start your call with us.</Instructions>
        <CallDestination>john.doe@example.onsip.com</CallDestination>
        <Theme>flat-light</Theme>
        <VideoEnabled>true</VideoEnabled>
        <DtmfEnabled>true</DtmfEnabled>
        <RemoveLogo>false</RemoveLogo>
        <CallerId>caller-name</CallerId>
        <CallerIdTag/>
        <ButtonText>Click to Call John Doe</ButtonText>
        <AnalyticsWebPropertyId/>
        <AnalyticsDomainName/>
        <AltPhone/>
        <AltEmail/>
        <AltWebsite/>
        <bhr0open/>
        <bhr1open/>
        <bhr2open/>
        <bhr3open/>
        <bhr4open/>
        <bhr5open/>
        <bhr6open/>
        <bhr0close/>
        <bhr1close/>
        <bhr2close/>
        <bhr3close/>
        <bhr4close/>
        <bhr5close/>
        <bhr6close/>
        <TimeZone/>
        <PostCallMessage/>
        <FromURI/>
        <ButtonCode>&lt;button class=&quot;ic-button&quot; data-instaCallName=&quot;ExampleOne&quot; data-Instructions=&quot;Start your call with us.&quot; data-address=&quot;john.doe@example.onsip.com&quot; data-video=&quot;true&quot; data-dtmf=&quot;true&quot; data-callerId=&quot;caller-name&quot; data-callerIdTag=&quot;&quot; data-theme=&quot;flat-light&quot; data-analyticsWebPropertyId=&quot;&quot; data-analyticsDomainName=&quot;&quot; data-altPhone=&quot;&quot; data-altEmail=&quot;&quot; data-altWebsite=&quot;&quot; data-postmessage=&quot;&quot; title=&quot;To make a web call, please enable Javascript for your browser.&quot; disabled=&quot;disabled&quot;&gt;Click to Call John Doe&lt;/button&gt;&lt;script src=&quot;https://insta.onsip.com/call/js/popup.js&quot;&gt;&lt;/script&gt;</ButtonCode>
      </Instacall>
    </InstacallGenerate>
  </Result>
</Response>

Unauthenticated OnSIP User Destination

Similar to the configuration above, InstaCall buttons can also be configured to invite OnSIP users in domains without authentication enabled. While the previous configuration would still work, without authentication enabled you can take advantage of custom From URIs. Rather than using a randomly generated anonymous SIP address, each InstaCall can be given a descriptive SIP address to send from.

ParametersValue
CallDestination Your SIP address (e.g. john.doe@example.onsip.com)
CallerId "caller-name", to prompt the visitor for their name.
ButtonText “Click to Call {Your Name}” (e.g, “Click to Call John Doe”)
FromURI Descriptive SIP address in your domain (e.g. instacall.blog@example.onsip.com). The From URI could also be left unspecified, which would use an anonymous SIP address.

In the example request below, John Doe generates an InstaCall button for his blog, choosing a unique SIP address (instacall.blog@example.onsip.com) to know which calls he receives from this button.

1
2
3
4
5
curl -X POST \
--user john.doe@example.onsip.com:mysuperpassword \
--data \
'Action=InstacallGenerate&InstacallName=ExampleOne&OrganizationId=12345&CallDestination=john.doe%40example.onsip.com&CallerId=caller-name&ButtonText=Click to Call John Doe&FromURI=instacall.blog@example.onsip.com' \
https://api.onsip.com/api

Sample response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
<?xml version="1.0" encoding="UTF-8"?>
<Response xmlns="http://www.jnctn.net/ns/rest/2006-01">
  <Context>
    <Action>
      <IsCompleted>true</IsCompleted>
    </Action>
    <Request>
      <IsValid>true</IsValid>
      <DateTime>2014-04-16T17:41:21+00:00</DateTime>
      <Duration>56</Duration>
      <Parameters>
        <Parameter>
          <Name>Action</Name>
          <Value>InstacallGenerate</Value>
        </Parameter>
        <Parameter>
          <Name>InstacallName</Name>
          <Value>ExampleOne</Value>
        </Parameter>
        <Parameter>
          <Name>OrganizationId</Name>
          <Value>12345</Value>
        </Parameter>
        <Parameter>
          <Name>CallDestination</Name>
          <Value>john.doe@example.onsip.com</Value>
        </Parameter>
        <Parameter>
          <Name>CallerId</Name>
          <Value>caller-name</Value>
        </Parameter>
        <Parameter>
          <Name>ButtonText</Name>
          <Value>Click to Call John Doe</Value>
        </Parameter>
        <Parameter>
          <Name>FromURI</Name>
          <Value>instacall.blog@example.onsip.com</Value>
        </Parameter>
        <Parameter>
          <Name>VideoEnabled</Name>
          <Value>true</Value>
        </Parameter>
        <Parameter>
          <Name>DtmfEnabled</Name>
          <Value>true</Value>
        </Parameter>
        <Parameter>
          <Name>RemoveLogo</Name>
          <Value>false</Value>
        </Parameter>
        <Parameter>
          <Name>Theme</Name>
          <Value>flat-light</Value>
        </Parameter>
      </Parameters>
    </Request>
    <Session>
      <Stateless>true</Stateless>
      <IsEstablished>true</IsEstablished>
      <SessionId>d89e98ce72a06b156b3335616a584736</SessionId>
      <UserId>54321</UserId>
      <Roles>
        <Role>
          <Name>Account Admin</Name>
        </Role>
      </Roles>
    </Session>
  </Context>
  <Result>
    <InstacallGenerate>
      <Instacall>
        <InstacallId/>
        <InstacallName>ExampleOne</InstacallName>
        <Instructions>Start your call with us.</Instructions>
        <CallDestination>john.doe@example.onsip.com</CallDestination>
        <Theme>flat-light</Theme>
        <VideoEnabled>true</VideoEnabled>
        <DtmfEnabled>true</DtmfEnabled>
        <RemoveLogo>false</RemoveLogo>
        <CallerId>caller-name</CallerId>
        <CallerIdTag/>
        <ButtonText>Click to Call John Doe</ButtonText>
        <AnalyticsWebPropertyId/>
        <AnalyticsDomainName/>
        <AltPhone/>
        <AltEmail/>
        <AltWebsite/>
        <bhr0open/>
        <bhr1open/>
        <bhr2open/>
        <bhr3open/>
        <bhr4open/>
        <bhr5open/>
        <bhr6open/>
        <bhr0close/>
        <bhr1close/>
        <bhr2close/>
        <bhr3close/>
        <bhr4close/>
        <bhr5close/>
        <bhr6close/>
        <TimeZone/>
        <PostCallMessage/>
        <FromURI>instacall.blog@example.onsip.com</FromURI>
        <ButtonCode>&lt;button class=&quot;ic-button&quot; data-instaCallName=&quot;ExampleOne&quot; data-Instructions=&quot;Start your call with us.&quot; data-address=&quot;john.doe@example.onsip.com&quot; data-video=&quot;true&quot; data-dtmf=&quot;true&quot; data-callerId=&quot;caller-name&quot; data-callerIdTag=&quot;&quot; data-theme=&quot;flat-light&quot; data-analyticsWebPropertyId=&quot;&quot; data-analyticsDomainName=&quot;&quot; data-altPhone=&quot;&quot; data-altEmail=&quot;&quot; data-altWebsite=&quot;&quot; data-postmessage=&quot;&quot; data-fromURI=&quot;instacall.blog@example.onsip.com&quot; title=&quot;To make a web call, please enable Javascript for your browser.&quot; disabled=&quot;disabled&quot;&gt;Click to Call John Doe&lt;/button&gt;&lt;script src=&quot;https://insta.onsip.com/call/js/popup.js&quot;&gt;&lt;/script&gt;</ButtonCode>
      </Instacall>
    </InstacallGenerate>
  </Result>
</Response>

External (non-OnSIP) Destination

InstaCall buttons can be configured to deliver traffic to third-party applications. This can be a convenient way to add WebRTC functionality to your existing SIP services. While the previous examples could use anonymous SIP addresses as From URIs, delivering traffic outside of OnSIP requires the From URI to be a SIP address in an OnSIP Network domain with authentication disabled.

To learn more about why anonymous SIP addresses cannot be used to open relay and why the From URI must not be authenticated, check out the InstaCall Authentication guide.

Since we are delivering traffic to an external destination, let’s also tag the CallerID, so the external destination can better key filters based on the traffic.

ParametersValue
CallDestination The external SIP address to send InstaCalls to.
CallerId "caller-name-tag", to prompt the visitor for their name.
CallerIdTag Unique characters to prefix Caller ID with (BLG)
ButtonText “Click to Call {Your Name}” (e.g, “Click to Call John Doe”)
FromURI A unique SIP address in your OnSIP Network domain (instacall.blog@example.onsip.com)

Again using John Doe as an example, here is what the API call could look like using cURL:

1
2
3
4
5
curl -X POST \
--user john.doe@example.onsip.com:mysuperpassword \
--data \
'Action=InstacallGenerate&InstacallName=ExampleOne&OrganizationId=12345&CallDestination=john.doe%40external.com&CallerId=caller-name-tag&CallerIdTag=BLG&ButtonText=Click to Call John Doe' \
https://api.onsip.com/api

Sample response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
<?xml version="1.0" encoding="UTF-8"?>
<Response xmlns="http://www.jnctn.net/ns/rest/2006-01">
  <Context>
    <Action>
      <IsCompleted>true</IsCompleted>
    </Action>
    <Request>
      <IsValid>true</IsValid>
      <DateTime>2014-04-16T16:04:27+00:00</DateTime>
      <Duration>50</Duration>
      <Parameters>
        <Parameter>
          <Name>Action</Name>
          <Value>InstacallGenerate</Value>
        </Parameter>
        <Parameter>
          <Name>InstacallName</Name>
          <Value>ExampleOne</Value>
        </Parameter>
        <Parameter>
          <Name>OrganizationId</Name>
          <Value>12345</Value>
        </Parameter>
        <Parameter>
          <Name>CallDestination</Name>
          <Value>john.doe@external.com</Value>
        </Parameter>
        <Parameter>
          <Name>CallerId</Name>
          <Value>caller-name</Value>
        </Parameter>
        <Parameter>
          <Name>CallerIdTag</Name>
          <Value>BLG</Value>
        </Parameter>
        <Parameter>
          <Name>ButtonText</Name>
          <Value>Click to Call John Doe</Value>
        </Parameter>
        <Parameter>
          <Name>VideoEnabled</Name>
          <Value>true</Value>
        </Parameter>
        <Parameter>
          <Name>DtmfEnabled</Name>
          <Value>true</Value>
        </Parameter>
        <Parameter>
          <Name>RemoveLogo</Name>
          <Value>false</Value>
        </Parameter>
        <Parameter>
          <Name>Theme</Name>
          <Value>flat-light</Value>
        </Parameter>
      </Parameters>
    </Request>
    <Session>
      <Stateless>true</Stateless>
      <IsEstablished>true</IsEstablished>
      <SessionId>9921c554c48ba60417a8dac8edbbe611</SessionId>
      <UserId>54321</UserId>
      <Roles>
        <Role>
          <Name>Account Admin</Name>
        </Role>
      </Roles>
    </Session>
  </Context>
  <Result>
    <InstacallGenerate>
      <Instacall>
        <InstacallId/>
        <InstacallName>ExampleOne</InstacallName>
        <Instructions>Start your call with us.</Instructions>
        <CallDestination>john.doe@external.com</CallDestination>
        <Theme>flat-light</Theme>
        <VideoEnabled>true</VideoEnabled>
        <DtmfEnabled>true</DtmfEnabled>
        <RemoveLogo>false</RemoveLogo>
        <CallerId>caller-name-tag</CallerId>
        <CallerIdTag>BLG</CallerId>
        <ButtonText>Click to Call John Doe</ButtonText>
        <AnalyticsWebPropertyId/>
        <AnalyticsDomainName/>
        <AltPhone/>
        <AltEmail/>
        <AltWebsite/>
        <bhr0open/>
        <bhr1open/>
        <bhr2open/>
        <bhr3open/>
        <bhr4open/>
        <bhr5open/>
        <bhr6open/>
        <bhr0close/>
        <bhr1close/>
        <bhr2close/>
        <bhr3close/>
        <bhr4close/>
        <bhr5close/>
        <bhr6close/>
        <TimeZone/>
        <PostCallMessage/>
        <FromURI/>
        <ButtonCode>&lt;button class=&quot;ic-button&quot; data-instaCallName=&quot;ExampleOne&quot; data-Instructions=&quot;Start your call with us.&quot; data-address=&quot;john.doe@external.com&quot; data-video=&quot;true&quot; data-dtmf=&quot;true&quot; data-callerId=&quot;caller-name-tag&quot; data-callerIdTag=&quot;BLG&quot; data-theme=&quot;flat-light&quot; data-analyticsWebPropertyId=&quot;&quot; data-analyticsDomainName=&quot;&quot; data-altPhone=&quot;&quot; data-altEmail=&quot;&quot; data-altWebsite=&quot;&quot; data-postmessage=&quot;&quot; title=&quot;To make a web call, please enable Javascript for your browser.&quot; disabled=&quot;disabled&quot;&gt;Click to Call John Doe&lt;/button&gt;&lt;script src=&quot;https://insta.onsip.com/call/js/popup.js&quot;&gt;&lt;/script&gt;</ButtonCode>
      </Instacall>
    </InstacallGenerate>
  </Result>
</Response>

Topics: Developer Docs