Copyright 2020 ONDEWO GmbH
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License. (editesyntax = "proto3";
rpc CreateFHIRSurvey (CreateFHIRSurveyRequest) returns (Survey)Create a Survey from FHIR format and an empty NLU Agent for it
rpc GetFHIRSurveyAnswers (GetSurveyAnswersRequest) returns (SurveyFHIRAnswersResponse)Get Survey Answers on FHIR format
rpc GetAllFHIRSurveyAnswers (GetAllSurveyAnswersRequest) returns (SurveyFHIRAnswersResponse)Get all Survey Answers on FHIR format
Method Name | Method | Pattern | Body |
CreateFHIRSurvey | POST | /fhir_survey | * |
GetFHIRSurveyAnswers | GET | /survey/{survey_id=*}/fhir_answers/{session_id=*} | |
GetAllFHIRSurveyAnswers | GET | /survey/{survey_id=*}/fhir_answers |
Field | Type | Label | Description |
fhir_questionnaire | google.protobuf.Struct | FHIR questionnaire on a gRPC Struct format |
Field | Type | Label | Description |
survey_id | string | The project identifier for this survey. Equal to the parent of the corresponding Agent.
Format: `projects/ |
|
fhir_questionnaire_responses | google.protobuf.Struct | repeated | all requested answers |
Copyright 2020 ONDEWO GmbH
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License. (editesyntax = "proto3";
rpc CreateSurvey (CreateSurveyRequest) returns (Survey)Create a Survey and an empty NLU Agent for it
rpc GetSurvey (GetSurveyRequest) returns (Survey)Retrieve a Survey message from the Database and return it
rpc UpdateSurvey (UpdateSurveyRequest) returns (Survey)Update an existing Survey message from the Database and return it
rpc DeleteSurvey (DeleteSurveyRequest) returns (.google.protobuf.Empty)Delete a survey and its associated agent (if existent)
rpc ListSurveys (ListSurveysRequest) returns (ListSurveysResponse)Returns the list of all surveys in the server
rpc GetSurveyAnswers (GetSurveyAnswersRequest) returns (SurveyAnswersResponse)Retrieve answers to survey questions collected in interactions with a survey agent for a specific session
rpc GetAllSurveyAnswers (GetAllSurveyAnswersRequest) returns (SurveyAnswersResponse)Retrieve all answers to survey questions collected in interactions with a survey agent in any session
rpc CreateAgentSurvey (AgentSurveyRequest) returns (AgentSurveyResponse)Populate and configures an NLU Agent from a Survey
rpc UpdateAgentSurvey (AgentSurveyRequest) returns (AgentSurveyResponse)Update an NLU agent from a survey
rpc DeleteAgentSurvey (AgentSurveyRequest) returns (.google.protobuf.Empty)Deletes all data of an NLU agent associated to a survey
Method Name | Method | Pattern | Body |
CreateSurvey | POST | /survey | * |
GetSurvey | GET | /survey/{survey_id=*} | |
UpdateSurvey | PATCH | /survey/{survey_id=*} | * |
DeleteSurvey | DELETE | /survey/{survey_id=*} | |
ListSurveys | GET | /surveys | |
GetSurveyAnswers | GET | /survey/{survey_id=*}/answers/{session_id=*} | |
GetAllSurveyAnswers | GET | /survey/{survey_id=*}/answers | |
CreateAgentSurvey | POST | /survey/{survey_id=*}/agent | * |
UpdateAgentSurvey | PATCH | /survey/{survey_id=*}/agent | * |
DeleteAgentSurvey | DELETE | /survey/{survey_id=*}/agent/delete |
Field | Type | Label | Description |
survey_id | string | The project identifier for this survey. Equal to the parent of the corresponding Agent.
Format: `projects/ |
Field | Type | Label | Description |
parent | string | The parent of an agent. Equal to the survey ID.
Format: `projects/ |
Field | Type | Label | Description |
question_nr | int64 | the number of the question to which this answer belongs |
|
session_id | string | the ID of the session on which the answer was collected |
|
answer_text | string | Required; the full answer text |
|
answer_parameter | string | fixme: better names and doc-strings below Optional; contains the normalized value of the selected option (parameter) extracted |
|
answer_parameter_original | string | Optional; contains the original text of the selected option (parameter) extracted |
|
anonymous | bool |
|
|
user_information | Answer.UserInfo |
|
Field | Type | Label | Description |
first_name | string | First name of the User to be surveyed |
|
last_name | string | Last name of the User to be surveyed |
|
phone_number | string | Phone number of the User to be surveyed |
|
session_id | string | the ID of the session on which the answer was collected |
|
user_id | string | Unique identifier of the User to be surveyed |
The Choice message defines one "option" for the SingleChoiceQuestion and MultipleChoiceQuestion question types
Example: Choice(synonyms=["blue", "blueish", "pale blue", "deep blue"])
Field | Type | Label | Description |
synonyms | string | repeated | The synonyms which are recognized as equivalent for identifying one option |
follow_up_question | Question | Optional; Nested question if this specific choice gets chosen. Note: the follow-up question is only available for the SingleChoiceQuestion |
|
value | string | The "canonical value" (i.e. the entity value) |
Field | Type | Label | Description |
survey | Survey |
|
Field | Type | Label | Description |
survey_id | string | The project identifier for this survey. Equal to the parent of the corresponding Agent.
Format: `projects/ |
Field | Type | Label | Description |
survey_id | string | The project identifier for this survey. Equal to the parent of the corresponding Agent.
Format: `projects/ |
Field | Type | Label | Description |
survey_id | string |
|
|
session_id | string | ID of one specific session on which survey answers were collected (contains survey_id) |
|
user_id | string | User Identifier. Note, if the survey is anonymous there will no identifier to filter on |
|
user_phone_number | string | User phone number. Note, if the survey is anonymous there will no identifier to filter on |
Field | Type | Label | Description |
survey_id | string | The project identifier for this survey. Equal to the parent of the corresponding Agent.
Format: `projects/ |
Field | Type | Label | Description |
page_token | string | Optional. The next_page_token value returned from a previous list request. Example: "current_index-10--page_size-20" Start page -> 10 Page size -> 20 |
The response message for [Intents.ListIntents][google.cloud.dialogflow.v2.Intents.ListIntents].
Field | Type | Label | Description |
surveys | Survey | repeated | The list of surveys. There will be a maximum number of items returned based on the page_token field in the request. |
next_page_token | string | Token to retrieve the next page of results, or empty if there are no more results in the list. |
A question for which exactly one or more out of a predefined set of options are expected as answers
Example: MultipleChoiceQuestion(
question_text='Which colors do you like?',
choices=[
Choice(synonyms=['red', 'reddisch']),
Choice(synonyms=['blue', 'blueish']),
Choice(synonyms=['yellow']),
]
)
Field | Type | Label | Description |
question_text | string | The text which introduces the question (should be pronounceable) |
|
choices | Choice | repeated | List of choices which are accepted for this question Each Choice is represented by lists of synonyms. Note: needs to contain at least 2 choices |
MultipleParameterQuestion defines a question which prompts the user for one or several entities of one particular type
Example: MultipleParameterQuestion(question_text='How old are your children?', parameter_type='sys.number')
Field | Type | Label | Description |
question_text | string | The text which introduces the question (should be pronounceable) |
|
parameter_type | string | The display name of the entity (type) which is accepted as an answer to this question Note: the corresponding entity_type must exist (system entity type) and is not automatically created |
A question to which any kind of reply can be given and recorded
fixme: not working yet
Field | Type | Label | Description |
question_text | string | The text which introduces the question (should be pronounceable) |
Field | Type | Label | Description |
open_question | OpenQuestion |
|
|
single_choice_question | SingleChoiceQuestion |
|
|
multiple_choice_question | MultipleChoiceQuestion |
|
|
scale_question | ScaleQuestion | convenience wrapper around a SingleChoiceQuestion |
|
single_parameter_question | SingleParameterQuestion |
|
|
multiple_parameter_question | MultipleParameterQuestion |
|
A question for which an answer on a user-defined scale is expected
Field | Type | Label | Description |
question_text | string | The text which introduces the question (should be pronounceable) |
|
min_value | ScaleQuestion.ScaleValue |
|
|
max_value | ScaleQuestion.ScaleValue |
|
Field | Type | Label | Description |
value | int32 |
|
|
label | string |
|
A question for which exactly one out of a predefined set of options is expected as answer
Example: SingleChoiceQuestion(
question_text='Who is your favorite movie hero?',
choices=[
Choice(synonyms=['Bond', 'James Bond']),
Choice(synonyms=['Batman']),
Choice(synonyms=['Superman', 'Clark Kent']),
]
)
Field | Type | Label | Description |
question_text | string | The text which introduces the question (should be pronounceable) |
|
choices | Choice | repeated | List of choices which are accepted for this question Each Choice is represented by lists of synonyms. Note: needs to contain at least 2 choices |
SingleParameterQuestion defines a question which prompts the user for one entity of a particular type
Example: SingleParameterQuestion(question_text='How old are you?', parameter_type='sys.number')
Field | Type | Label | Description |
question_text | string | The text which introduces the question (should be pronounceable) |
|
parameter_type | string | The display name of the entity (type) which is accepted as an answer to this question Note: the corresponding entity_type must exist (system entity type) and is not automatically created |
Field | Type | Label | Description |
survey_id | string | The project identifier for this survey. Equal to the parent of the corresponding Agent.
Format: `projects/ |
|
display_name | string | Required. The (human readable) name of this survey |
|
language_code | string | Required. The language of the agent created for the survey. This is also the only supported language of the agent. ISO 639-1 language code |
|
questions | Question | repeated | Required. List of questions to be asked during the survey. |
survey_info | SurveyInfo | Required. Information about the entity behind the survey, the purpose of the survey, legal stuff, etc. |
|
exclude_subflows | SubFlow | repeated | Optional. List of subflows excluded for this survey. |
status | Survey.AgentStatus | Current status of the NLU Agent respecting to the Survey |
Field | Type | Label | Description |
survey_id | string | The project identifier for this survey. Equal to the parent of the corresponding Agent.
Format: `projects/ |
|
answers | Answer | repeated | all requested answers |
Collect information about the entity behind the survey, the purpose of the survey, legal stuff, etc.
This is needed to generate meaningful messages and training data for some of the auto-generated intents.
Field | Type | Label | Description |
legal_entity | string | Required unless SubFlow.LEGAL_ENTITY is deselected. The legal entity (company, research institute, etc.) on whose behalf the survey is performed |
|
postal_address | string | Required unless SubFlow.POSTAL_ADDRESS is deselected. The postal address to which callees can direct any requests. |
|
email_address | string | Required unless SubFlow.EMAIL_ADDRESS is deselected. The email address to which callees can direct any requests. |
|
phone_number | string | Required unless SubFlow.PHONE_NUMBER is deselected. The phone number to which callees can direct any requests. |
|
phone_hours | string | Required unless SubFlow.PHONE_HOURS is deselected. The phone hours during which callees can call (in pronounceable form). |
|
expected_duration | string | Required unless SubFlow.EXPECTED_DURATION is deselected. The expected duration of the survey (in pronounceable form) |
|
purpose | string | Required unless SubFlow.PURPOSE is deselected. An explanation regarding the purpose of the survey (in pronounceable form) |
|
topic | string | Required. A one-word explanation of the survey topic (in pronounceable form) |
|
legal_disclaimer | string | Required. A pronounceable explanation of the legal implications of participating in the survey. For example: "Your answers during this survey will be stored anonymously for the next two years and then deleted." Should be formulated such that the agent can afterwards ask for the consent of the user. Example for how the agent could continue: "Are you willing to participate in this survey?" |
|
anonymous | bool | Optional. Defaults to False. Allows the definition of a survey as anonymous or not. If the survey is not anonymous, the name of the people as well as their number will be recorded |
Field | Type | Label | Description |
survey | Survey | Updated survey. Note: the ID must refer to an existing survey which will be updated |
|
update_mask | google.protobuf.FieldMask | Optional. Field mask that defines which fields get updated. Default: all fields are updated. Example: - update_mask = FieldMask( [ 'survey.display_name', 'survey.questions' ] ) |
Enumeration of (some of) the subflows which are created by default
This can be used to "switch off" particular subflows when creating an agent during CreateSurvey
Subflows are defined as one of the following:
- sequences of intents A -> B_1, ..., B_n -> ... -> Z_1, ..., Z_m which are linked by context relationships
such that the first intent in the sequence can always be triggered
- single intents which can always be triggered
Name | Number | Description |
SUBFLOW_UNSPECIFIED | 0 | Not specified. This value should be never used. |
BOT | 1 | The subflow allowing the user to inquire whether s/he is talking to a bot |
LEGAL_ENTITY | 2 | The subflow allowing the user to inquire about the legal entity |
POSTAL_ADDRESS | 3 | The subflow allowing the user to inquire about the postal address |
EMAIL_ADDRESS | 4 | The subflow allowing the user to inquire about the email address |
PHONE_NUMBER | 5 | The subflow allowing the user to inquire about the phone number |
PHONE_HOURS | 6 | The subflow allowing the user to inquire about the phone hours |
EXPECTED_DURATION | 7 | The subflow allowing the user to inquire about the expected duration of the survey |
PURPOSE | 8 | The subflow allowing the user to inquire about the purpose of the survey |
Name | Number | Description |
TO_BE_INITIALIZED | 0 | |
UPDATED | 1 | |
UPDATING | 2 | |
OUTDATED | 3 |
.proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
double | double | double | float | float64 | double | float | Float | |
float | float | float | float | float32 | float | float | Float | |
int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum |
uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) |
uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) |
sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum |
fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) |
fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum |
sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum |
bool | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | |
string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) |
bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |