This method takes action on an alert, dispatching messages to recipients and recording interaction data.
| Client Servlet | Server Servlet | HTTP Methods Supported | Requires Authentication |
|---|---|---|---|
| CRAdvocacyAPI | SRAdvocacyAPI | POST | Server. |
https://secure2.convio.net/organization/site/CRAdvocacyAPI?method=takeAction &api_key=value &v=value [ &auth=value ] [ ¢er_id=value ] [ &error_redirect=value ] [ &redirect=value ] [ &response_format=xml | json ] [ &sign_redirects=value ] [ &source=value ] [ &sso_auth_token=value ] [ &sub_source=value ] [ &success_redirect=value ] [ &suppress_response_codes=value ] &alert_id=value &alert_type=action | call | lte [ &anonymous=value ] [ &body=value ] [ &called=value ] [ &cc=value ] [ &city=value ] [ &contact_name=value ] [ &contact_position=value ] [ &country=value ] [ &email=value ] [ &first_name=value ] [ &last_name=value ] [ ¬e=value ] [ &opt_in=value ] [ &phone=value ] [ &preview=value ] [ &recipient=all | internet | fax | print | call ] [ &reply=value ] [ &state=value ] [ &street1=value ] [ &street2=value ] [ &subject=value ] [ &survey=value ] [ &title=value ] [ &zip=value ]https://secure2.convio.net/organization/site/SRAdvocacyAPI?method=takeAction & api_key =value & login_name =value & login_password =value & v =value [ & center_id =value ] [ & cons_id =value ] [ & error_redirect =value ] [ & redirect =value ] [ & response_format =xml |json ] [ & sign_redirects =value ] [ & source =value ] [ & sub_source =value ] [ & success_redirect =value ] [ & suppress_response_codes =value ] & alert_id =value & alert_type =action |call |lte [ & anonymous =value ] [ & body =value ] [ & called =value ] [ & cc =value ] [ & city =value ] [ & contact_name =value ] [ & contact_position =value ] [ & country =value ] [ & email =value ] [ & first_name =value ] [ & last_name =value ] [ & note =value ] [ & opt_in =value ] [ & phone =value ] [ & preview =value ] [ & recipient =all |internet |fax |print |call ] [ & reply =value ] [ & state =value ] [ & street1 =value ] [ & street2 =value ] [ & subject =value ] [ & survey =value ] [ & title =value ] [ & zip =value ]VERY IMPORTANT: Testing with the Preview Option
Always set the preview parameter true when developing and testing with the takeAction API. This prevents the system from sending out unwanted messages and logging alert participation interactions in the database, but behaves just like a live interaction in other respects, returning the same API response that the live interaction would return.
General Usage
Use the takeAction method to submit an Advocacy alert. You must specify both the alert_id and the alert_type of the alert you wish to submit, as alert_id is not guaranteed unique across types.
Input parameters for takeAction may also require specific information returned by getAdvocacyAlert such as predefined message text, constituent address information, survey questions, and valid recipient IDs. When the valid recipient list varies depending on the consitutuent's legislative district, getAdvocacyAlert method determines the correct list based on the address of record for the logged-in user, or using an address provided as input.
Constituent Information
Many action alerts require constituent name and address information. If the constituent is logged in (or if the constituent record can be uniquely identified and the system is configured to allow it), the passed-in values of street1, street2, city, state, zip, country, and phone parameters will be used to update the constituent profile.
If a unique constituent record cannot be identified, the first_name, last_name, and email parameters along with the address and phone information will be used to create a new constituent profile.
Recipients
Specify recipients and delivery methods for the alert message by passing recipient parameters. To create recipient parameters, append the element value returned by getAdvocacyAlert to the word "recipient" as the parameter name, and assign a delivery method as the parameter value. The valid delivery method options for each recipient appear in the deliveryOptions
recipientrepresentative.-1=allBy default, if you do not specify recipients when calling takeAction on an action alert, the system will attempt delivery to all the recipients listed by getAdvocacyAlert for the action alert, using the delivery method(s) you defined when you created the alert.
Call alerts and LTE alerts require you to specify at least one valid recipient.
Survey Questions
If the action alert includes a survey, the survey question identifiers used to create survey response parameters are returned in the questionId element of the getAdvocacyAlert response for each survey question, for example: survey107_1040_1_1060
Where the questionType
Returning survey data requires passing the value as the parameter name and the response as the parameter value to takeAction. For example, the form input for a MultiSingle type question where the questionId
<p>How do you normally commute to work?</p>
<select name="survey107_1040_1_1060">
<option value="Walk, Run or Bike">Walk, Run or Bike</option>
<option value="Mass Transit">Mass Transit</option>
<option value="Carpool">Carpool</option>
<option value="Other">Other</option>
</select>You can respond to Captcha survey questions through the client API in the same way, using the questionId node value as the parameter name.
If your site is using ReCAPTCHA v3, then you'll need the publicKey returned by the call to getAdvocacyAlert which you will then pass to the ReCAPTCHA library. An example of this can be found in the documentation for getSurvey. Learn more about CAPTCHA.
questionTypeInteractive Web Forms/strong>
Web-based contact forms sometimes require users to complete an interactive challenge/response test (also known as CAPTCHA) to limit spam. The takeActionAPI cannot deliver messages via an interactive web form. In particular, a significant percentage (150-200 out of 535) of Federal congressional webforms are interactive. Alternatively, you can direct users to the recipient's contact web site so they can interact with the web form directly. The urlinteractive
See topic Common Parameters.
Required. Specify the alert.
Type xsd:positiveInteger.
Required. Specify the alert type.
Type advocacyAlertType.
Optional. Specify that the interaction is anonymous.
Type xsd:boolean.
Default is false.
Optional. Editable portion of message body. May be required by alert configuration.
Type xsd:string.
Optional. Call date. Required for call alerts. Ignored for other types of alerts.
Type xsd:date.
Optional. Specify that the constituent wants to get a copy of the message sent to targets.
Type xsd:boolean.
Default is false.
Optional. Constituent city.
Type xsd:string.
Optional. Call contact name. Optional for call alerts. Ignored for other types of alerts.
Type xsd:string.
Optional. Call contact position. Required for call alerts. Ignored for other types of alerts.
Type xsd:string.
Optional. Constituent country.
Type xsd:string.
Optional. Constituent email address.
Type xsd:string.
Optional. Constituent first name.
Type xsd:string.
Optional. Constituent last name.
Type xsd:string.
Optional. Call note. Required for call alerts. Ignored for other types of alerts.
Type xsd:string.
Optional. Specify that the constituent is opting in. The default is the same as the alert configuration.
Type xsd:boolean.
Optional. Constituent phone. May be required by alert configuration.
Type xsd:string.
Optional. Designates a test participation. Always specify preview=true when testing. When true, the participation will be processed and the result returned to the caller, but the messages will not be sent, and the interaction will not be logged in the database.
Type xsd:boolean.
Default is false.
Optional. Select recipients and delivery methods.
Type advocacyDelivery.
Optional. Call reply. Required for call alerts. Ignored for other types of alerts.
Type xsd:string.
Optional. Constituent state.
Type xsd:string.
Optional. Constituent street 1.
Type xsd:string.
Optional. Constituent street 2.
Type xsd:string.
Optional. Message subject. May be required by alert configuration.
Type xsd:string.
Optional. Survey answers prefix.
Type xsd:string.
Optional. Constituent title. May be required by alert configuration.
Type xsd:string.
Optional. Constituent zip.
Type xsd:string.
See topic Common Parameters.
Optional. Specifies the constituent associated with the alert or action.
Type xsd:nonNegativeInteger.
Optional. Specifies that redirect URLs should be signed with a timestamp and a hash of the query string arguments and a secret key.
Type xsd:boolean.
Default is false.
Required. Specify the alert.
Type xsd:positiveInteger.
Required. Specify the alert type.
Type advocacyAlertType.
Optional. Specify that the interaction is anonymous.
Type xsd:boolean.
Default is false.
Optional. Editable portion of message body. May be required by alert configuration.
Type xsd:string.
Optional. Call date. Required for call alerts. Ignored for other types of alerts.
Type xsd:date.
Optional. Specify that the constituent wants to get a copy of the message sent to targets.
Type xsd:boolean.
Default is false.
Optional. Constituent city.
Type xsd:string.
Optional. Call contact name. Optional for call alerts. Ignored for other types of alerts.
Type xsd:string.
Optional. Call contact position. Required for call alerts. Ignored for other types of alerts.
Type xsd:string.
Optional. Constituent country.
Type xsd:string.
Optional. Constituent email address.
Type xsd:string.
Optional. Constituent first name.
Type xsd:string.
Optional. Constituent last name.
Type xsd:string.
Optional. Call note. Required for call alerts. Ignored for other types of alerts.
Type xsd:string.
Optional. Specify that the constituent is opting in. The default is the same as the alert configuration.
Type xsd:boolean.
Optional. Constituent phone. May be required by alert configuration.
Type xsd:string.
Optional. Designates a test participation. Always specify preview=true when testing. When true, the participation will be processed and the result returned to the caller, but the messages will not be sent, and the interaction will not be logged in the database.
Type xsd:boolean.
Default is false.
Optional. Select recipients and delivery methods.
Type advocacyDelivery.
Optional. Call reply. Required for call alerts. Ignored for other types of alerts.
Type xsd:string.
Optional. Constituent state.
Type xsd:string.
Optional. Constituent street 1.
Type xsd:string.
Optional. Constituent street 2.
Type xsd:string.
Optional. Message subject. May be required by alert configuration.
Type xsd:string.
Optional. Survey answers prefix.
Type xsd:string.
Optional. Constituent title. May be required by alert configuration.
Type xsd:string.
Optional. Constituent zip.
Type xsd:string.
See topic HTTP Status Codes.
XML response<?xml version="1.0" encoding="UTF-8"?>
<takeActionResponse xsi:schemaLocation="http://convio.com/crm/v1.0 http://service.convio.net/xmlschema/crm.public.v1.xsd" xmlns="http://convio.com/crm/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<interaction>
<interactionId>1001</interactionId>
<interacted>2018-10-03T11:01:16.362-05:00</interacted>
<alert>
<alertId>103</alertId>
<type>action</type>
<status>active</status>
<priority>high</priority>
<url>https://secure2.convio.net/orgname/site/Advocacy?pagename=homepage&amp;id=103</url>
<interactionCount>1000002</interactionCount>
<title>Alert Title</title>
<thumbnail>https://secure2.convio.net/orgname/images/Thumbnails/ActionAlerts/103</thumbnail>
<internalName>Internal Name</internalName>
<description>Description</description>
<category categoryId="1">General</category>
<issues>
<issue issueId="1001">Issue1</issue>
<issue issueId="1002">Issue2</issue>
</issues>
<restrictByState>
<state>TN</state>
<state>TX</state>
</restrictByState>
<modified>2018-10-03T11:01:16.362-05:00</modified>
<publish>2018-10-03T11:01:16.362-05:00</publish>
<expire>2018-10-03T11:01:16.362-05:00</expire>
<targets>
<target>Governor</target>
<target>US Senator</target>
<target>US Representative</target>
<target>State Senator</target>
<target>State Representative</target>
</targets>
<messageSubject>Subject</messageSubject>
<messageSubjectEditable>optional</messageSubjectEditable>
<messageGreeting>Dear</messageGreeting>
<messageOpening>Message Opening Text</messageOpening>
<messageBody>Message Body Text</messageBody>
<messageBodyEditable>optional</messageBodyEditable>
<messageClosing>Sincerely,</messageClosing>
<messageSignature>Signature</messageSignature>
<wordLimit>0</wordLimit>
<position>none</position>
<yeaCount>0</yeaCount>
<nayCount>0</nayCount>
<abstainCount>0</abstainCount>
</alert>
<recipients>
<recipient>
<recipientId>ID</recipientId>
<name>Senator John Q. Public</name>
<url>http://public.senate.gov/contact.cfm</url>
<interactive>true</interactive>
<deliveryOptions>
<delivery>internet</delivery>
</deliveryOptions>
</recipient>
</recipients>
<subject>Subject</subject>
<body>Body</body>
<called>2018-10-03T11:01:16.362-05:00</called>
<contactPosition>ContactPosition</contactPosition>
<contactName>ContactName</contactName>
<reply>Reply</reply>
<note>Note</note>
</interaction>
</takeActionResponse>{"takeActionResponse":{"interaction":{"note":"Note","interactionId":"1001","called":"2018-10-03T11:01:16.365-05:00","alert":{"messageGreeting":"Dear","messageSubjectEditable":"optional","description":"Description","type":"action","title":"Alert Title","issues":{"issue":[{"issueId":"1001","content":"Issue1"},{"issueId":"1002","content":"Issue2"}]},"targets":{"target":["Governor","US Senator","US Representative","State Senator","State Representative"]},"internalName":"Internal Name","messageBodyEditable":"optional","messageClosing":"Sincerely,","yeaCount":"0","nayCount":"0","messageSignature":"Signature","modified":"2018-10-03T11:01:16.366-05:00","messageOpening":"Message Opening Text","alertId":"103","interactionCount":"1000002","abstainCount":"0","thumbnail":"https://secure2.convio.net/orgname/images/Thumbnails/ActionAlerts/103","messageBody":"Message Body Text","messageSubject":"Subject","priority":"high","wordLimit":"0","url":"https://secure2.convio.net/orgname/site/Advocacy?pagename=homepage&id=103","publish":"2018-10-03T11:01:16.366-05:00","expire":"2018-10-03T11:01:16.365-05:00","restrictByState":{"state":["TN","TX"]},"position":"none","category":{"categoryId":"1","content":"General"},"status":"active"},"recipients":{"recipient":{"name":"Senator John Q. Public","interactive":"true","recipientId":"ID","url":"http://public.senate.gov/contact.cfm","deliveryOptions":{"delivery":"internet"}}},"subject":"Subject","contactName":"ContactName","interacted":"2018-10-03T11:01:16.365-05:00","contactPosition":"ContactPosition","body":"Body","reply":"Reply"}}}Survey Questions: DateQuestion
When returning a response to a DateQuestion type survey question, You must pass each part of the date value (the month, day, and year, and, optionally, the hour, minute, and second) as individual parameters to takeAction. For each date part, create separate parameter by appending one of the following to the the base survey parameter name: _YEAR, _MONTH, _DAY, _HOUR24 (or _HOUR12 and _AMPM ), _MINUTE, _SECOND.
For example, given the following DateQuestion type survey question in the getAdvocacyAlert response:
<question>
<questionId>survey107_1000_1_1000</questionId>
<questionType>DateQuestion</questionType>
<text>Please update your DOB?</text>
<value>
<required>true</required>
<questionChoices>
<minSelected>0</minSelected>
<maxSelected>0</maxSelected>
<imageUrl>
<audioUrl>
</audioUrl></imageUrl></questionChoices></value></question>You might render the survey question in an HTML form as:
<label for="survey107_1000_1_1000">Please update your DOB?</label><br>
<fieldgroup id="survey107_1000_1_1000">
<input type="text" name="survey107_1000_1_1000_MONTH" size="2" value="MM"> -
<input type="text" name="survey107_1000_1_1000_DAY" size="2" value="DD"> -
<input type="text" name="survey107_1000_1_1000_YEAR" size="4" value="YYYY"> <br>
</fieldgroup>The value posted to takeAction representing the response would look like:
survey107_1000_1_1000_YEAR=2010&survey107_1000_1_1000_MONTH=6&survey107_1000_1_1000_DAY=18Survey Questions: ComboChoice
A ComboChoice survey question presents users two options. They can either pick from a list of predefined values, or they can supply an alternate value not on the list. This is rendered using an HTML "select" type input for the predefined list, a "text" input for the alternate value, and "radio" type inputs to choose between them.
You must return each part of a ComboChoice survey question as an individual parameter by postfixing the word "survey" in the the base survey parameter name with radio_, select_, or text_, as appropriate.
For example, given the following ComboChoice question in the getAdvocacyAlert response:
<question>
<questionId>survey107_1000_2_1001</questionId>
<questionType>ComboChoice</questionType>
<text>Please update your suffix?</text>
<value>
<required>false</required>
<questionChoices>
<choice name="Sr." selected="false">Sr.</choice>
<choice name="Jr." selected="false">Jr.</choice>
<choice name="II" selected="false">II</choice>
<choice name="III" selected="false">III</choice>
<choice name="IV" selected="false">IV</choice>
</questionChoices>
<minSelected>0</minSelected>
<maxSelected>0</maxSelected>
<imageUrl>
<audioUrl>
</audioUrl></imageUrl></value></question>You might render the survey question in an HTML form as:
<label for="survey107_1000_2_1001">Please update your suffix?</label><br>
<fieldgroup id="survey107_1000_2_1001">
<input type="radio" name="surveyradio_107_1000_2_1001" value="1">
<select name="surveyselect_107_1000_2_1001">
<option>Sr.</option><option>Jr.</option><option>II</option><option>III</option><option>IV
</option></select>
<input type="radio" name="surveyradio_107_1000_2_1001" value="2">
<input type="text" name="surveytext_107_1000_2_1001">
</fieldgroup>If the user selects one of the predefined values, the parameters posted to takeAction should look like this:
surveyselect_107_1000_2_1001=Sr.&surveyradio_107_1000_2_1001=1If the user supplies a different value, the parameters posted to takeAction should look like this:
surveytext_107_1000_2_1001=PhD.&surveyradio_107_1000_2_1001=2If you specify only a surveytext value, that value will be used whether it is one of the predefined choices or another value:
surveytext_107_1000_2_1001=PhD.