save_project creates and changes one, and
get and search with kind: "project" read it.
Projects are in beta. They are on for every account in the buyer beta, and off
for every other account, where
save_project and the project kind of get
and search are refused with FEATURE_NOT_ENABLED. This release stores and
reads Projects. It does not yet let an agent act on its own inside the bounds,
stop or resume one, archive one, show its progress, or list a Buyer account’s
chats with search of kind session.What a Project holds
createdByUserId records who created the Project. It grants no access.
Create a Project
save_project without an id creates one. It needs name and a clientRequestId;
repeating the call with the same clientRequestId returns the same Project and the
same conversation.
ACCESS_DENIED. To
create a Project for an advertiser the person must be able to operate it, and
changing one needs the same write access: a person who can only read the advertiser can
read the Project and cannot change it.
The conversation
A create makes the Project’s conversation in the same call: a chat titled with the Project’s name, shared with everyone who can read the Project, with the Project’s lead as its lead. The chat belongs to the Project. It cannot be deleted, archived or made private on its own, and its lead is always the Project’s lead, sosave_session
refuses to change or remove it.
Instead of a new chat, a create can adopt one of yours with sessionId, once. The
chat keeps its participants and its owner, the Project’s lead becomes its lead, and
the previous lead stays on as an expert. The call is refused with
NOT_FOUND if you cannot read the chat, and then with VALIDATION_ERROR, naming the
reason, when the chat:
- belongs to someone else (sharing gives read access, so only the chat’s owner can adopt it; a topic Session an agent started has no owner and needs only to be readable);
- is already a Project’s conversation;
- is not active;
- is private (share it first with the shared-chat control);
- concerns another advertiser than the Project’s, or concerns no advertiser at all (advertiser Projects only: a chat with no advertiser can carry any advertiser’s context, so it cannot become the conversation of one advertiser’s Project);
- has a person in it who cannot read the Project, or an agent that does not cover the Project’s advertiser.
Who can read a Project
Everyone who can operate the Project’s advertiser reads the Project, its conversation and every thread in it. An account-level Project is read by every account member who can read every advertiser its attachments concern. Reading or posting in the conversation needs that access every time, whoever else is in the chat.save_session refuses to add a person who cannot read the Project.
Attachments
An attachment is acampaign, media_buy, rfp or connection, with a relation
of subject, request, response, evidence or outcome. On an advertiser
Project, a campaign, media_buy or rfp must belong to that advertiser, and one
whose record names no advertiser is refused. A connection belongs to the account,
not to an advertiser, so it can be attached to any Project. A material or an
exchange is refused with NOT_IMPLEMENTED for now.
To change them, send attach or detach with an id. Detaching a media buy that
the bounds list as a target saves a narrower revision without it.
Bounds
bounds are AdCP’s governance plan fields (budget, flight, channels,
countries, regions, policy_ids, policy_categories, approved_sellers,
human_review_required) plus three of ours:
autonomousActions: which ofmove_budget,change_pacing,pause_or_resume_media_buyandassign_approved_creativethe lead may take without asking;limits:maxActionsPerDay(1 to 50, default 10) andiuBudget;targets.mediaBuyIds: the attached media buys those actions may change.
budget takes reallocation_threshold, in the budget currency. reallocation_unlimited
is refused: an autonomous move needs a ceiling a person approved.
custom_policies is not available yet and is refused with NOT_IMPLEMENTED; use
policy_ids and policy_categories.
Bounds change only through approval on our site. Narrower means different things
for the two kinds of list. A list of what may be used or done (countries, regions,
channels.allowed, approved_sellers, autonomousActions) narrows by losing entries.
A list of what must hold (channels.required, policy_ids, policy_categories)
narrows by gaining entries, so dropping a required channel or a policy waits for
approval. A revision that is not narrower in
every field than the approved one returns approval_required with a link, and takes
effect when an administrator of the account, or of its Organization, approves that
exact revision. Repeat the call to see the outcome. A revision narrower in every field
saves at once and keeps the same approver. The Project’s own lead agent may save such a narrower revision
itself, with no new approval; it can change nothing else, and a wider revision from it is refused with
ACCESS_DENIED. The Project becomes active once its
bounds are approved and the flight has started. A flight that has already ended is
refused.
Read and search
search with kind: "project" lists the Projects you can read, newest first, and takes
filter.state (any of draft, active, paused, archived), filter.advertiserId and
filter.includeArchived, which is false unless you set it or ask for the archived
state. A page holds at most 25 Projects whatever limit you send, and nextCursor
continues it. The text lists one line per Project, and get returns the whole Project.
A Buyer cannot yet read a Project’s conversation through search or get with
kind: "session": use the Project’s sessionId and the web chat.