Concepts

Campaigns

A high-level task definition for agent(s) to complete for each Job, such as performing affordable housing surveys, contacting customers to finish filling out their insurance policies, or being the first line for an inbound customer support line to answer questions or escalate to a human.

Campaigns are the highest order unit of information for completing work: All analytics, jobs, and data belong to a campaign.

Jobs

A Job is an instance of a Campaign executing for a contact.

Multiple Jobs can share the same contact (e.g. calling the power company’s phone number 300 times to activate power for a new development), but each Job has its own context for scheduling calls and completing the campaign.

Jobs only require a phone number to create, but can take additional information such as a contact name, as well as arbitrary metadata in JSON form such as internal user IDs, state, zip code, customer type, etc. that can be used during reporting and context for the agent’s conversation with this contact. This metadata may also be used for templating the agent context (e.g. an invoice ID, name of someone you’d like to be connected to).

If an inbound call matches multiple Jobs by phone number, then the most recently updated Job will be selected to restore context. Outbound calls don’t require conflict resolution, and there are different Campaign configurations to handle inbound calls.

Job End States

Jobs will end in either one of the completed, canceled or failed states (deleted will be the final state if you delete PII from a Job).

completed state

The completed state means that we were able to talk to the intended contact, and were able to non-erroneously collect information such that another call is not required.

If the campaign has a CampaignObjectivePrompt set, then the job will only be in the completed state if the LLM evaluates the job to also have met the objective.

Otherwise, completed only means that there is no more to do based on the previous conversation. But maybe the job wasn’t “successful” on the sense of what you were trying to accomplish with the campaign.

failed state

A job might be in the failed state for two reasons:

The campaign objective was not met

If the campaign has a CampaignObjectivePrompt set, and the LLM evaluates the job to have failed said objective, then the job will be in the failed state, with the job’s FailureReason set to campaign_objective_missed.

A well-known failure

These things that would be a failure in any campaign, such as:

• Never picked up (max attempts exceeded)
• User refused to cooperate
• Phone number belonged to someone else
• Unrecoverable configuration error
• and others

You can see the specific reason for a Job failure from the Job data’s FailureReason and FailureMessage.

Failures still collect data

Note that failure does not mean the agents were unable to collect “any” information: The analysis result will contain all information for the schema that the agent was able to collect, and will have null in places where it was unable to obtain an answer (even if the schema required the field).

failed != nothing learned. Even just knowing that it was the wrong contact, or that a user does not want to talk can be useful information.

Personally Identifiable Information (PII)

Jobs must at some point contain PII such as phone number, contact name, or any information collected during the agent’s conversation with the contact.

Job PII must be explicitly deleted, regardless of Job state.

This is to ensure that you are able to download all the information that is needed from the Job before we clear out the system.

Once PII is deleted, it is unrecoverable, so ensure you’ve stored any information you need in your systems before performing this action.

PII should never be included in the Job Metadata field as it is not deleted during PII deletion. Use Data to store PII. The Data field gets cleared when PII is deleted.

In Metadata you should only include non-PII like state, zip code, etc. but no info should be able to be used to identify someone directly (e.g. a name, IP address, email, etc.).

Job Analysis

When Jobs are completed, or fail, they are analyzed by a dedicated analysis agent to structure as much information together as possible.

Analysis will either:

• Schedule the next call (e.g. contact asked for a call back)
• Opt out the contact (e.g. they asked to not be called again, hang up = opt out setting on Campaign or Job)
• Complete the Job with structued output (JSON) based on the Campaign’s analysis schema

Test Jobs

When creating a Job, you can provide "TestJob": true to indicate this is a test job. This will be filtered out from analytics, but still included in billing.

A test job always forces the call to immediately schedule, and will never retry for any reason.

Analytics events will have the properties.test_job = true if this is a test job, otherwise it may be false or undefined.

Inbound Mode

Cobbery campaigns will handle inbound calls back to a given number based on which mode it is configured in.

reject

All inbound calls will be rejected, and not incur any billed time. Will notify the caller that this number does not accept calls. Can customize this message.

lookup

Inbound calls will only be accepted if there is an existing Job with a phone number matching the caller.

This ensures that only contacts who were previously called can call back.

If multiple Jobs exist for the same phone number, the most recently updated Job will be used.

lookup_failed

Same as lookup, but allows to resume jobs that previously had failed.

create_if_not_exists

Same as lookup, however if no matching Job is found, a new Job will be created for this caller.

This mode is useful for handling both callbacks and new inbound inquiries in the same campaign.

create

When set to create, every inbound call will create a new Job, even if there are existing Jobs with the same phone number. This ensures each interaction is treated as a fresh conversation without any previous context.

This mode is ideal for general customer support lines where each call should be handled independently.

This does not mean that create can never have any context about a user, Cobbery agents are still able to retrieve internal and external information at call time for a user if required (e.g. lookup what previous support cases they’ve had)